second-brain-joplin

An MCP server that turns your Joplin knowledge base into searchable memory for any MCP-capable AI client — Claude Code, Cursor, and others.

Inspired by second-brain-mcp (for Obsidian). This project covers the same use case for Joplin: your AI assistant reads, searches, and files notes directly, without leaving the tool you already use.

Status: Pre-alpha — the four read tools are live; note creation is still stubbed (human-gated write lands in v0.4). See the roadmap and open issues.

How it works

Joplin Desktop exposes a local REST API on localhost:41184 (the Web Clipper service). This server wraps that API as MCP tools, so your AI client can query and update your notes in real time — no export step, no sync lag.

Claude Code / Cursor
       │  MCP
       ▼
second-brain-joplin (this server)
       │  HTTP + token
       ▼
Joplin Desktop (localhost:41184)
       │
       ▼
Your notes

Prerequisites

• Joplin Desktop running with the Web Clipper service enabled:
  Tools → Options → Web Clipper → Enable Web Clipper Service
• API token — copy it from the Web Clipper settings panel
• Python ≥ 3.11 or uvx (recommended — no install needed)

Quickstart

Claude Code

claude mcp add -s user second-brain-joplin \
  -e JOPLIN_API_TOKEN=your-token-here \
  -- uvx second-brain-joplin serve

Other MCP clients

See docs/install.md for per-client setup guides.

MCP Tools

The four read tools query a running Joplin instance as of v0.2. joplin_create is still stubbed; the human-gated write flow is tracked in the v0.4 milestone.

vs. second-brain-mcp (Obsidian)

Notebook structure

The PARA method works well with Joplin. See docs/notebook-structure.md for a recommended setup.

Roadmap

Security & privacy

This server keeps your notes local: it talks only to Joplin's Web Clipper REST API on localhost and runs on your own machine. Anything an MCP client can read, the connected AI can read — so apply least privilege and don't expose notebooks with credentials or other sensitive data. Note creation is planned as an explicit human-gated flow (v0.4); v0.1 does no silent writes. See SECURITY.md for details and how to report a vulnerability.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome — especially for testing against different Joplin versions and OS platforms.

License

MIT — see LICENSE.