Agentic-Joplin
Tooling that lets coding agents integrate with Joplin, the open-source note-taking app.
The project has three planned pieces:
| Piece | Status |
|---|---|
| MCP server — wraps Joplin's Data API as Model Context Protocol tools | ✅ Phase 1 complete |
| Joplin plugin — in-app plugin for capabilities the Data API can't expose | 🔜 planned |
| Agent skills — skill files teaching agents how to use Joplin effectively | ✅ Claude Code + Codex plugin |
This repo is an npm-workspaces monorepo; each piece lives under packages/.
MCP server
packages/mcp-server is a from-scratch Model Context Protocol server (TypeScript, stdio transport) that gives an agent full CRUD over Joplin notes, notebooks, tags, and resources, plus search, note revision history, and a connectivity check — 26 tools across 7 groups. It wraps Joplin's local Data API (the REST service exposed by the desktop app's Web Clipper).
Requirements
- Node.js ≥ 20
- Joplin desktop running with the Web Clipper service enabled (Options → Web Clipper), and an API token generated there.
Setup
npm install
npm run build --workspace @agentic-joplin/mcp-server
Then add it to your MCP client (e.g. Claude Code / Claude Desktop) as a stdio server running node packages/mcp-server/dist/index.js, with these environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
JOPLIN_TOKEN |
yes | — | API token from Joplin's Web Clipper settings |
JOPLIN_HOST |
no | 127.0.0.1 |
Host of the Web Clipper service |
JOPLIN_PORT |
no | 41184 |
Port of the Web Clipper service |
Joplin must be running with Web Clipper enabled for any tool call to succeed.
Tool surface
Notes (create_note, get_note, update_note, delete_note, list_notes), notebooks (get_notebook, list_notebooks, create_notebook, update_notebook, delete_notebook), tags (get_tag, list_tags, create_tag, update_tag, delete_tag, tag_note, untag_note), search (find_notes), resources (attach_resource, get_resource, update_resource, delete_resource, list_note_resources), revisions (list_note_revisions, delete_note_revisions), and ping.
Notes can be created in Markdown (default) or HTML via a format parameter. See packages/mcp-server/README.md for the full per-tool reference and packages/mcp-server/SMOKE_TEST.md for the manual release checklist.
Agent skills plugin
packages/plugin is a single plugin — valid for both Claude Code andCodex — that bundles the Joplin MCP server with four agent skills (using-joplin hub plusjoplin-capturing-notes, joplin-searching-and-updating, joplin-organizing). Seepackages/plugin/README.md for install steps on each platform.
Development
npm run build # type-check + compile all workspaces
npm test # run all workspace unit tests (mocked Data API, no Joplin instance needed)
Design docs live under docs/superpowers/: the design spec and the implementation plan.
License
TBD.
