joplin-mcp

A minimal MCP server for Joplin, built with FastMCP. Talks to Joplin's local Web Clipper REST API.

Tools

• search_notes(query, limit=20) — full-text search
• get_note(note_id) — fetch a note's full content
• create_note(title, body, notebook_id) — create a new note
• update_note(note_id, title=None, body=None) — edit an existing note
• list_notebooks() — list notebooks, to get a notebook_id for create_note

Setup

1. In Joplin Desktop: Tools > Options > Web Clipper, enable the service, copy the auth token shown there.
2. Set the token as an environment variable (don't hardcode it in configs you might commit or share):

   export JOPLIN_TOKEN="paste-your-token-here"
   

   Or drop it into the .env file at the repo root (already gitignored) and pass --env-file .env to uv run instead — see below.
3. Install uv if you don't have it.
4. Set JOPLIN_ALLOWED_NOTEBOOKS to a comma-separated list of notebook ids and/or names (get these from list_notebooks) — see Access control below.

Running it

No manual pip install needed — uv run resolves and caches dependencies on first run.

uv run --directory /path/to/joplin-mcp joplin-mcp-server

To load JOPLIN_TOKEN (and friends) from the .env file instead of exporting them in your shell:

uv run --env-file .env --directory /path/to/joplin-mcp joplin-mcp-server

Wiring into an MCP client

Both approaches below point uv at the .env file rather than duplicating JOPLIN_TOKEN/JOPLIN_ALLOWED_NOTEBOOKS into the client config — one source of truth for secrets.

Claude Code

claude mcp add joplin -s user -- uv run --env-file /path/to/joplin-mcp/.env --directory /path/to/joplin-mcp joplin-mcp-server

-s user registers it at user scope, so it's available in every Claude Code session, not just this repo. Verify with claude mcp get joplin; remove with claude mcp remove joplin -s user.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), adding:

{
  "mcpServers": {
    "joplin": {
      "command": "uv",
      "args": ["run", "--env-file", "/path/to/joplin-mcp/.env", "--directory", "/path/to/joplin-mcp", "joplin-mcp-server"]
    }
  }
}

Fully quit and restart Claude Desktop afterward — it only picks up config changes on launch. This is the schema documented at support.claude.com and modelcontextprotocol.io. Some Claude Desktop builds manage MCP servers through a Settings UI (Extensions/Connectors) instead of this file directly — check there first if the file on disk doesn't have an mcpServers key already.

Migrating to uvx later

Once this repo is stable and pushed, the local uv run --directory ... invocation above can be replaced with:

uvx --from git+https://github.com/johnsarie27/joplin-mcp@<pinned-sha> joplin-mcp-server

pinning <pinned-sha> to a specific commit per the SHA-pinning convention, so client configs aren't silently pulling main on every run. No local checkout needed at that point — just swap the command/args in whichever client config above to uvx/--from git+... instead of uv/run --env-file ... --directory ....

Testing standalone (recommended before wiring into a client)

npx @modelcontextprotocol/inspector uv run --env-file .env --directory /path/to/joplin-mcp joplin-mcp-server

This opens a local web UI where you can call each tool manually and see the raw request/response before trusting it to a model.

Access control

search_notes, get_note, create_note, and update_note are scoped to notebooks listed in JOPLIN_ALLOWED_NOTEBOOKS (comma-separated notebook ids and/or names). This is fail-closed: if the variable is unset, empty, or none of its entries match a real notebook, all four tools refuse to operate. list_notebooks is unaffected since it only returns notebook metadata, not note content, and doubles as the way to find the ids/names to allowlist in the first place.

Name matching is case-insensitive (Tech, tech, and TECH are equivalent) and resolved against the live notebook list on each call, so a rename takes effect immediately. Since Joplin doesn't require notebook names to be unique (nested notebooks can share a title), a name that matches more than one notebook allows all of them — use the notebook id instead (from list_notebooks) if you need to scope to just one of several same-named notebooks.

Set JOPLIN_ALLOWED_NOTEBOOKS=* to explicitly allow all notebooks. This is a deliberate opt-in, distinct from leaving the variable unset.

Out-of-scope access raises a NotebookAccessError with a message naming the notebook, distinct from a JoplinError (an actual Joplin API failure).

Notes on this build

• Requires Joplin Desktop running with the Web Clipper service enabled (i.e. Joplin itself must be open — this doesn't run Joplin headlessly).
• JOPLIN_HOST / JOPLIN_PORT env vars override the defaults (localhost / 41184) if needed.
• Errors from the Joplin API surface as JoplinError with the raw status/body — check these first if a tool call fails.

References

• Joplin Data API

Related projects

• alondmnt/joplin-mcp
• dweigend/joplin-mcp-server