Jotter MCP server

A Model Context Protocol server that lets an AI agent collaborate inside a Jotter note — reading and editing it live, and showing up in the collaborator menu as “<your verified name> (AI)” so the humans in the note can tell the agent apart.

How it works

The agent authenticates with a premium account API key. It acts as that account on exactly the notes the account has saved — nothing else. Under the hood it connects to the same real-time CRDT WebSocket a browser uses, so its edits merge live with everyone else and it appears as a present collaborator.

The badge name comes from the server (it’s derived from your account’s verified name and can’t be spoofed); the (AI) suffix marks it as an agent.

Setup

1. Create an API key

Sign in to Jotter with a Plus account, open Account settings → API keys, and create a key. Copy it — it’s shown only once. (It looks like jot_ai_….)

2. Save the notes you want the agent to touch

The agent can only see and edit notes saved to your account. “Sharing” a note with your agent just means saving it (and, for PIN notes, you must have saved it after entering the PIN — that’s what proves access).

3. Register it with your MCP client

The server runs straight from npm with npx — nothing to clone or build. For Claude Code:

claude mcp add jotter \
  --env JOTTER_API_KEY=jot_ai_your_key_here \
  -- npx -y jotter-mcp

To point at a non-production instance, also pass --env JOTTER_URL=https://….

Any MCP client works — give it the command npx -y jotter-mcp with the JOTTER_API_KEY (and optional JOTTER_URL) environment variables.

Contributing? To run from source instead, clone the repo and use cd mcp && npm install && npm run build, then point your client at node /absolute/path/to/notes-app/mcp/dist/index.js.

Configuration

| Variable | Required | Default | Notes | | ----------------- | -------- | -------------------- | ---------------------------------- | | JOTTER_API_KEY | yes | — | A premium account key (jot_ai_…) | | JOTTER_URL | no | https://jotter.at | Base URL of the Jotter instance |

Tools

| Tool | Arguments | Description | | -------------- | ---------------------- | -------------------------------------------------------------------------- | | list_notes | — | List notes the account has saved (slug + title). | | read_note | slug | Read the full Markdown of a note. | | wait_for_edit| slug, timeoutSeconds? | Block until someone else edits the note, then return it — for live co-writing. | | append_note | slug, text | Append Markdown to the end of the note. | | edit_note | slug, find, replace | Replace one exact, unique run of text with new text — leaves the rest untouched. | | replace_note | slug, text | Replace the entire note body with new Markdown. |

edit_note is the safe choice for a partial change: it splices only the matched span, so a person editing the same note at the same time is not overwritten. replace_note rewrites the whole body and will clobber a concurrent editor — reserve it for a deliberate full rewrite. find must appear exactly once; include surrounding context if a phrase repeats.

Security notes

• The key carries no scope of its own — access is resolved live from your saved notes on every request. Unsave a note and the agent loses access to it immediately.
• The key never grants owner-only actions (delete, publish, change PIN, revoke share links). Those remain account-UI-only.
• Revoke a key any time from Account settings → API keys. The raw key is shown only at creation and stored only as a hash.