Joplin MCP Server — Claude Code MCP server: features and setup
Connect an AI assistant to Joplin to search and edit notes, manage tags, and import files. You’ll need a Joplin API token to configure access.
claude mcp add --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_URL=<JOPLIN_URL> --transport stdio joplin-mcp-server -- uvx joplin-mcpWhat Joplin MCP Server does
This MCP server lets an AI assistant work with Joplin notes, notebooks, and tags. It can find and edit notes, create entries, and restore items from the trash. For attached images and PDFs, it can retrieve OCR text.
The server also imports Markdown, HTML, CSV, TXT, and JEX files, as well as directories. You can limit access to selected notebooks with path patterns, including nested notebooks and exclusions. Read, write, update, and delete permissions can be configured separately. Joplin’s Web Clipper service must be enabled, and its API token is required for the connection.
What it helps with
- search Joplin notes by topic or tag
- create notes in a chosen notebook
- organize entries with tags
- import Markdown or CSV files into Joplin
- restrict assistant access to selected notebooks
Example prompts for the agent
- Find my Joplin notes about Python and show the relevant ones.
- Create a note about today’s meeting in the Work notebook.
- Import
notes.mdinto Joplin and tag the new note as important.
How to install Joplin MCP Server
Platform CLI
claude mcp add --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_URL=<JOPLIN_URL> --transport stdio joplin-mcp-server -- uvx joplin-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>
Platform CLI
codex mcp add joplin-mcp-server --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_URL=<JOPLIN_URL> -- uvx joplin-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>
Config file
{
"mcpServers": {
"joplin-mcp-server": {
"command": "uvx",
"args": [
"joplin-mcp"
],
"env": {
"JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
"JOPLIN_URL": "<JOPLIN_URL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>
Config file
{
"servers": {
"joplin-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"joplin-mcp"
],
"env": {
"JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
"JOPLIN_URL": "<JOPLIN_URL>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>
Platform CLI
gemini mcp add -e JOPLIN_TOKEN=<JOPLIN_TOKEN> -e JOPLIN_URL=<JOPLIN_URL> joplin-mcp-server uvx joplin-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Joplin MCP Server
How do I install Joplin MCP Server in Claude Code?
Run claude mcp add joplin-mcp -e JOPLIN_TOKEN=<JOPLIN_TOKEN> -- uvx joplin-mcp. First enable the Web Clipper service in Joplin and copy its API token.
What does Joplin MCP Server do?
It gives an AI assistant MCP access to Joplin notes, notebooks, and tags. The assistant can search and edit notes, import files, and manage tags.
Can I limit which notebooks the assistant can access?
Yes. Set notebook_allowlist or JOPLIN_NOTEBOOK_ALLOWLIST to define permitted notebook paths. Patterns can cover nested notebooks or exclude specific paths.
