second-brain-joplin 0.2.0

MCP server that connects Claude Code (and other MCP clients) to your Joplin knowledge base

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

Setting	Value
Command	uvx second-brain-joplin serve
JOPLIN_API_TOKEN	token from Joplin Web Clipper settings
JOPLIN_BASE_URL	http://localhost:41184 (default)

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

---

MCP Tools

Tool	Description	Writes?
joplin_overview	List all notebooks with note counts	No
joplin_search	Keyword search across all notes	No
joplin_read	Read a note by ID	No
joplin_recent	Notes modified in the last N days	No
joplin_create	Create a note (human-gated)	Yes

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)

	second-brain-mcp	second-brain-joplin
Note app	Obsidian	Joplin
Storage	Plain .md files on disk	Joplin REST API
Requires app running	No	Yes (Joplin + Web Clipper)
Semantic search	Yes (bge-m3)	Planned (v0.3)
Write support	Human-gated	Human-gated (v0.4)
Install	uvx second-brain-mcp	uvx second-brain-joplin

---

Notebook structure

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

---

Roadmap

Milestone	Theme	Status
v0.1 — Bootstrap	Repo, CI, package skeleton	Done
v0.2 — Core Read Tools	All read MCP tools working	Done
v0.3 — Semantic Search	Embedding index, semantic search	Planned
v0.4 — Write Workflow	Human-gated note creation	Planned
v1.0 — Publish	PyPI, full docs, templates	Planned

---

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.