joplin-mcp-server — Claude Code MCP server for Joplin notes
Lets your coding agent work with Joplin notes and notebooks: look things up, read them, write new ones, edit existing ones. Handy when your notes live in Joplin.
claude mcp add --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_HOST=<JOPLIN_HOST> --env JOPLIN_PORT=<JOPLIN_PORT> --env JOPLIN_PROFILE=<JOPLIN_PROFILE> --env JOPLIN_CLI=<JOPLIN_CLI> --transport stdio jordanburke-joplin-mcp-server -- npx -y joplin-mcp-serverWhat joplin-mcp-server does
The server runs its own Joplin Terminal instance as a sidecar and exposes it over MCP. You do not need the desktop app, and nothing gets installed globally. When Joplin Desktop is already up, the sidecar picks a free port between 41184 and 41193 and runs next to it. Note data sits in ~/.config/joplin-mcp by default, apart from any desktop install.
Start it with npx joplin-mcp-server --token your_joplin_token. The token is required. Sync is configured through --sync-target and --sync-path, with filesystem, webdav, nextcloud, joplin-cloud, joplin-server, s3, dropbox and onedrive supported. Filesystem paths accept ~ and environment variables, and on WSL the server falls back to the matching Windows path when ~/ is empty. To talk to an instance that is already running, set JOPLIN_HOST or JOPLIN_PORT and the sidecar stays off.
No token means no server, so sort that out first. Transport defaults to stdio; HTTP comes with --transport http on port 3000.
What it helps with
- find a note by phrase without opening Joplin
- save an agent answer as a new note
- edit text inside an existing notebook
- keep notes in sync across machines
- reach a Joplin instance on another host
Example prompts for the agent
- Find my Joplin notes about deployment and show the latest one
- Create a note called "Weekly summary" in the Work notebook
- Read the API note and append a task list to it
How to install joplin-mcp-server
Platform CLI
claude mcp add --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_HOST=<JOPLIN_HOST> --env JOPLIN_PORT=<JOPLIN_PORT> --env JOPLIN_PROFILE=<JOPLIN_PROFILE> --env JOPLIN_CLI=<JOPLIN_CLI> --transport stdio jordanburke-joplin-mcp-server -- npx -y joplin-mcp-serverReplace <…> with your own values. 8 more environment variables are in the server README
Platform CLI
codex mcp add jordanburke-joplin-mcp-server --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_HOST=<JOPLIN_HOST> --env JOPLIN_PORT=<JOPLIN_PORT> --env JOPLIN_PROFILE=<JOPLIN_PROFILE> --env JOPLIN_CLI=<JOPLIN_CLI> -- npx -y joplin-mcp-serverReplace <…> with your own values. 8 more environment variables are in the server README
Config file
{
"mcpServers": {
"jordanburke-joplin-mcp-server": {
"command": "npx",
"args": [
"-y",
"joplin-mcp-server"
],
"env": {
"JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
"JOPLIN_HOST": "<JOPLIN_HOST>",
"JOPLIN_PORT": "<JOPLIN_PORT>",
"JOPLIN_PROFILE": "<JOPLIN_PROFILE>",
"JOPLIN_CLI": "<JOPLIN_CLI>"
}
}
}
}Replace <…> with your own values. 8 more environment variables are in the server README
Config file
{
"servers": {
"jordanburke-joplin-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"joplin-mcp-server"
],
"env": {
"JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
"JOPLIN_HOST": "<JOPLIN_HOST>",
"JOPLIN_PORT": "<JOPLIN_PORT>",
"JOPLIN_PROFILE": "<JOPLIN_PROFILE>",
"JOPLIN_CLI": "<JOPLIN_CLI>"
}
}
}
}Replace <…> with your own values. 8 more environment variables are in the server README
Platform CLI
gemini mcp add -e JOPLIN_TOKEN=<JOPLIN_TOKEN> -e JOPLIN_HOST=<JOPLIN_HOST> -e JOPLIN_PORT=<JOPLIN_PORT> -e JOPLIN_PROFILE=<JOPLIN_PROFILE> -e JOPLIN_CLI=<JOPLIN_CLI> jordanburke-joplin-mcp-server npx -y joplin-mcp-serverReplace <…> with your own values. 8 more environment variables are in the server README
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-server -e JOPLIN_TOKEN=<JOPLIN_TOKEN> -e JOPLIN_SYNC_PASSWORD=<JOPLIN_SYNC_PASSWORD> -- npx -y joplin-mcp-server. A Joplin token is required.
What does joplin-mcp-server do?
It starts Joplin Terminal as a sidecar and gives the agent search, read, create and edit access to your notes and notebooks over MCP.
Do I need Joplin Desktop installed?
No. The Joplin CLI ships inside the server. If the desktop app is running, the sidecar grabs a free port and both keep syncing.
