Agentic-Joplin MCP Server
Provides full CRUD over Joplin notes, notebooks, tags, and resources, plus search, note revision history, and connectivity check, enabling AI agents to manage a Joplin note-taking instance.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 | ✅ Published to npm as |
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).
Setup
The server is published to npm as agentic-joplin:
npx -y -p agentic-joplin agentic-joplin-authorize # one time: click Accept in Joplin; caches a tokenThen add it to your MCP client (e.g. Claude Code / Claude Desktop) as a stdio server:
{
"mcpServers": {
"joplin": { "command": "npx", "args": ["-y", "agentic-joplin"] }
}
}To run from source instead: npm install && npm run build --workspace agentic-joplin, then point the client at node packages/mcp-server/dist/index.js.
Environment variables:
Variable | Required | Default | Description |
| no | — | API token from Joplin's Web Clipper settings. Falls back to the token cached in |
| no |
| Host of the Web Clipper service |
| no |
| 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.
Related MCP server: Joplin Server MCP
Agent skills plugin
packages/plugin is a single plugin — valid for both Claude Code and
Codex — that bundles the Joplin MCP server with four agent skills (using-joplin hub plus
joplin-capturing-notes, joplin-searching-and-updating, joplin-organizing). See
packages/plugin/README.md for install steps on each platform.
The four skills are listed on skills.sh. To install only the four skills, without the plugin bundle, use the skills CLI (Node.js 22.20 or later). It records the source, so npx skills update keeps them current. The skills still need the Joplin MCP server above.
# All four skills, globally
npx skills add sohampatwardhan/Agentic-Joplin -g
# One skill, for chosen agents only
npx skills add sohampatwardhan/Agentic-Joplin -g --skill using-joplin -a claude-code -a codex
# Update later
npx skills update -gCompanion skills for richer notes
Joplin renders Mermaid diagrams and KaTeX math natively. The Joplin skills work on their own, but when these two optional Agent Skills are installed they defer to them for diagrams and formulas:
mermaid— picks a diagram type and writes validated Mermaid.katex— writes KaTeX-safe math with Joplin's$/$$delimiters.
Install the Joplin skills and both companions together with skills:
npx skills add sohampatwardhan/Agentic-Joplin -g
npx skills add sohampatwardhan/mermaid-skill -g
npx skills add sohampatwardhan/KaTeX-Agent-Skill -gIf a companion is missing, the agent may offer to install it, but only runs the command after you say yes.
Development
npm run build # type-check + compile all workspaces
npm test # check skill versions, then run all workspace unit tests (mocked Data API, no Joplin instance needed)
npm run check:skills # only check that every SKILL.md has a valid SemVer metadata.versionSkill versioning
Each SKILL.md carries a SemVer 2.0.0 version in its
frontmatter metadata map (a string-to-string map, so quote the value):
metadata:
author: sohampatwardhan
version: "1.0.0"Bump a skill's version on any change to it:
PATCH for wording and fixes.
MINOR for new guidance or behaviour.
MAJOR for breaking changes, such as renames or removed steps.
CI and npm test fail if any SKILL.md lacks metadata.version or the value isn't valid SemVer.
Design docs live under docs/superpowers/: the design spec and the implementation plan.
License
MIT © Soham Patwardhan
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Joplin note-taking app, enabling AI to read, search, and modify notes via sandboxed scripts.222 npm27Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for Joplin Server that gives LLMs full access to notes, notebooks, tags, and attachments via the REST API.8MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that turns your Joplin notebook into a tool an LLM can actually use — read, search, write, and organize notes, and pull OCR'd text straight out of your screenshots.131MIT
- AlicenseNot gradedqualityCmaintenanceExposes Joplin's Data API as MCP tools so an LLM can search, read, create, update, delete, and organize notes, notebooks, and tags against a headless Joplin instance, including attachments and tag management.1MIT