by jordanburke
Manage notes and notebooks seamlessly with Joplin. Create, edit, search, and organize todos and hierarchies via the REST
Provides complete access to Joplin notes through the REST API, allowing you to search, create, edit, and organize notes and notebooks.
Joplin is a community-built MCP server published by jordanburke that provides AI assistants with tools and capabilities via the Model Context Protocol. Manage notes and notebooks seamlessly with Joplin. Create, edit, search, and organize todos and hierarchies via the REST It is categorized under productivity.
You can install Joplin in your AI client of choice. Use the install panel on this page to get one-click setup for Cursor, Claude Desktop, VS Code, and other MCP-compatible clients. This server runs locally on your machine via the stdio transport.
MIT
Joplin is released under the MIT license. This is a permissive open-source license, meaning you can freely use, modify, and distribute the software.
Add new capabilities to Claude beyond text generation
Example
Access external data sources, execute code, interact with tools and services
Transform Claude from chatbot to action-taking agent
Provide Claude with access to relevant context and data
Example
Load project documentation, access knowledge bases, query databases
Get more accurate, context-aware responses
Automate multi-step workflows combining AI and external tools
Example
Research → Summarize → Create document → Send notification
Complete complex tasks end-to-end without manual steps
Share your MCP server with the developer community
I recommend Joplin for teams standardizing on MCP; the explainx.ai page compares cleanly with sibling servers.
We wired Joplin into a staging workspace; the listing’s GitHub and npm pointers saved time versus hunting across READMEs.
We wired Joplin into a staging workspace; the listing’s GitHub and npm pointers saved time versus hunting across READMEs.
Joplin is a well-scoped MCP server in the explainx.ai directory — install snippets and categories matched our Claude Code setup.
Useful MCP listing: Joplin is the kind of server we cite when onboarding engineers to host + tool permissions.
According to our notes, Joplin benefits from clear Model Context Protocol framing — fewer ambiguous “AI plugin” claims.
Strong directory entry: Joplin surfaces stars and publisher context so we could sanity-check maintenance before adopting.
I recommend Joplin for teams standardizing on MCP; the explainx.ai page compares cleanly with sibling servers.
We evaluated Joplin against two servers with overlapping tools; this profile had the clearer scope statement.
Joplin has been reliable for tool-calling workflows; the MCP profile page is a good permalink for internal docs.
showing 1-10 of 30
A self-contained MCP (Model Context Protocol) server for Joplin. Bundles the Joplin Terminal CLI as a dependency — no desktop app, no global installs, no external processes to manage. Coexists with Joplin Desktop via automatic port negotiation.
npx joplin-mcp-server --token your_joplin_token
That's it. The server spawns its own Joplin Terminal instance (sidecar mode), syncs to your configured backend, and exposes your notes via MCP.
The server bundles joplin as an npm dependency and manages its own Joplin Terminal process. No Joplin desktop app needed — the sidecar handles everything: data storage, sync, and the REST API.
If Joplin Desktop is already running, the sidecar automatically finds a free port (scanning 41184-41193) and runs alongside it. Both instances stay in sync if configured with the same sync target.
# Basic usage — sidecar starts automatically
npx joplin-mcp-server --token your_token
# With cloud sync
npx joplin-mcp-server --token your_token \
--sync-target joplin-cloud \
--sync-username [email protected] --sync-password pass
# With filesystem sync (e.g. OneDrive folder)
npx joplin-mcp-server --token your_token \
--sync-target filesystem \
--sync-path /mnt/c/Users/you/OneDrive/Joplin
The Joplin CLI is resolved in this order: JOPLIN_CLI env var > node_modules/.bin/joplin (bundled) > global install > npx fallback.
Data is stored in ~/.config/joplin-mcp by default (separate from any desktop Joplin install).
Connects to an existing Joplin instance instead of spawning a sidecar. Activated by setting JOPLIN_HOST or JOPLIN_PORT.
# Connect to Joplin desktop on another machine or Windows host
JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token
| Variable | Description | Default |
|---|---|---|
JOPLIN_TOKEN | API token (required) | -- |
JOPLIN_HOST | Connect to existing Joplin at this host (skips sidecar) | -- |
JOPLIN_PORT | Connect to existing Joplin on this port (skips sidecar) | -- |
JOPLIN_CLI | Path to joplin CLI binary (overrides auto-detection) | -- |
JOPLIN_PROFILE | Joplin data directory for sidecar mode | ~/.config/joplin-mcp |
JOPLIN_SYNC_TARGET | Sync target type | none |
JOPLIN_SYNC_PATH | Sync target URL/path | -- |
JOPLIN_SYNC_USERNAME | Sync username/email | -- |
JOPLIN_SYNC_PASSWORD | Sync password | -- |
LOG_LEVEL | Log level: debug, info, warn, error | info |
OPTIONS:
--env-file <file> Load environment variables from file
--token <token> Joplin API token
--transport <type> Transport type: stdio (default) or http
--http-port <port> HTTP server port (default: 3000, only with --transport http)
--profile <dir> Joplin data directory (default: ~/.config/joplin-mcp)
--sync-target <type> Sync target: none, filesystem, webdav, nextcloud,
joplin-cloud, joplin-server, s3, dropbox, onedrive
--sync-path <url> URL or path for sync target
--sync-username <user> Username/email for sync
--sync-password <pass> Password for sync
--help, -h Show help message
The --sync-path and --profile options support ~ and environment variable expansion for cross-platform compatibility:
# Tilde expands to home directory (Linux, macOS, Windows)
--sync-path ~/OneDrive/Apps/Joplin
# Environment variables (both forms supported)
--sync-path ${HOME}/OneDrive/Apps/Joplin
--sync-path $HOME/OneDrive/Apps/Joplin
# Windows example using USERPROFILE
--sync-path ${USERPROFILE}/OneDrive/Apps/Joplin
This works in MCP client configs (.mcp.json, Claude Desktop) where shell expansion isn't available.
WSL auto-detection: On WSL, if a ~/ path is empty or missing, the server automatically checks the corresponding Windows path at /mnt/c/Users/<user>/.... This means --sync-path ~/OneDrive/Apps/Joplin just works on WSL without needing the full /mnt/c/... path.
| Target | Required Options |
|---|---|
none | (default, no sync) |
filesystem | --sync-path /path/to/dir |
webdav | --sync-path <url> --sync-username --sync-password |
nextcloud | --sync-path <url> --sync-username --sync-password |
joplin-cloud | --sync-username --sync-password |
joplin-server | --sync-path <url> --sync-username --sync-password |
s3 | --sync-path <bucket> --sync-username <access-key> --sync-password <secret-key> |
dropbox | (OAuth flow) |
onedrive | (OAuth flow) |
The repository includes a .mcp.json that works with Claude Code's env var expansion:
{
"mcpServers": {
"joplin": {
"command": "node",
"args": ["dist/bin.js"],
"env": {
"JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
}
}
}
}
Set JOPLIN_TOKEN in your shell (add to ~/.bashrc or ~/.zshrc):
export JOPLIN_TOKEN="your_actual_token_here"
Claude Desktop does not support ${VAR} expansion. Provide values directly:
{
"mcpServers": {
"joplin": {
"command": "npx",
"args": ["joplin-mcp-server", "--token", "your_actual_token_here"]
}
}
}
{
"mcpServers": {
"joplin": {
"command": "npx",
"args": [
"joplin-mcp-server",
"--token",
"your_token",
"--sync-target",
"filesystem",
"--sync-path",
"/path/to/sync/dir"
]
}
}
}
{
"mcpServers": {
"joplin": {
"command": "npx",
"args": ["joplin-mcp-server"],
"env": {
"JOPLIN_TOKEN": "your_actual_token_here",
"JOPLIN_HOST": "192.168.0.40",
"JOPLIN_PORT": "41184"
}
}
}
}
docker build -t joplin-mcp .
docker run -e JOPLIN_TOKEN=your_token -p 3000:3000 joplin-mcp
Running in WSL? The sidecar architecture makes this straightforward — no Windows port forwarding needed. The server auto-detects WSL and handles path resolution between Linux and Windows filesystems.
Both your Windows Joplin desktop and the WSL sidecar sync to the same OneDrive folder. They see the same notes without needing to talk to each other directly.
# Uses ~/OneDrive — automatically resolves to /mnt/c/Users/YourName/OneDrive on WSL
npx joplin-mcp-server --token your_token \
--sync-target filesystem \
--sync-path ~/OneDrive/Apps/Joplin
# Or specify the Windows path explicitly
npx joplin-mcp-server --token your_token \
--sync-target filesystem \
--sync-path /mnt/c/Users/YourName/OneDrive/Apps/Joplin
In your Joplin desktop app, configure sync to the same OneDrive folder: Tools > Options > Synchronisation > File system > /Users/YourName/OneDrive/Apps/Joplin
Joplin Desktop coexistence: If Desktop is running on port 41184, the sidecar automatically uses the next available port. A warning is logged at startup reminding you that both instances use separate databases and need the same sync target to stay in sync.
Alternatively, both instances can sync to Joplin Cloud or any other cloud backend:
npx joplin-mcp-server --token your_token \
--sync-target joplin-cloud \
--sync-username [email protected] --sync-password pass
If you prefer to connect directly to Windows Joplin instead of running a sidecar:
On Windows (PowerShell as Administrator):
netsh interface portproxy add v4tov4 listenport=41184 listenaddress=0.0.0.0 connectport=41184 connectaddress=127.0.0.1
In WSL:
JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token
Find your Windows IP with ipconfig on Windows or cat /etc/resolv.conf | grep nameserver from WSL.
| Tool | Description |
|---|
Prerequisites
Time Estimate
15-60 minutes depending on server complexity
Steps
Troubleshooting
✓ Do
✗ Don't
💡 Pro Tips
Architecture
Model Context Protocol standardizes how AI hosts (Claude, Cursor) communicate with external tools and data sources through server implementations.
Protocols
Compatibility
✓ Use when
Use when you need Claude to access external data, execute actions, or integrate with tools. Best for extending AI capabilities beyond conversation.
✗ Avoid when
Avoid when native integrations exist (use official APIs directly), for real-time critical systems, or when security/compliance requires zero external dependencies.