second-brain-joplin

CI PyPI

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.

Project links

Data verified by PyPI on Jul 1, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jomkz from gravatar.com jomkz

GitHub Statistics

Data verified by PyPI on Jul 1, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

test

Tags

ai claude joplin knowledge-base mcp second-brain

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

second_brain_joplin-0.2.0.tar.gz (128.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

second_brain_joplin-0.2.0-py3-none-any.whl (12.1 kB view details)

Uploaded Python 3

File details

Details for the file second_brain_joplin-0.2.0.tar.gz.

File metadata

  • Download URL: second_brain_joplin-0.2.0.tar.gz
  • Upload date:
  • Size: 128.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for second_brain_joplin-0.2.0.tar.gz
Algorithm Hash digest
SHA256 5e811ee7c0cf4441d8a249a73b052492093abfc76752b7d0d807c72ed096bdd7
MD5 b45c2ef7473811952a090cee02210e28
BLAKE2b-256 aa47e0d302adad16d1c0cdc14bd6d08d4cafcb8a37792345b8744e08e83c5f49

See more details on using hashes here.

Provenance

The following attestation bundles were made for second_brain_joplin-0.2.0.tar.gz:

Publisher: release.yml on jomkz/second-brain-joplin

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file second_brain_joplin-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for second_brain_joplin-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f2048c31d77ad570624da2eb8c7c53d03a7a82cb527dfe59a424bf688478e8c3
MD5 5ef7f1070954df55a0a09d76387a54c8
BLAKE2b-256 efab0bd721474fdd13685b40d7bd2d785875844978eb4288b45be8cf8ea02453

See more details on using hashes here.

Provenance

The following attestation bundles were made for second_brain_joplin-0.2.0-py3-none-any.whl:

Publisher: release.yml on jomkz/second-brain-joplin

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page