Every Joplin MCP Server Had the Same Problem, So I Wrote One in Rust
You open three terminal panes to run three concurrent agent sessions. Each session boots its configured MCP servers over stdio. Two seconds later, two of them are wedged waiting on the uv cache lock while the third spends a second and a half warming up a Python interpreter just to read a note from localhost.
If you run a single agent at a time, uvx is lovely. The moment you run parallel sessions across Claude Code, Codex, and Antigravity (agy), every new session spawns its own uvx wrapper, contends on the same shared cache, and pays the Python startup tax before a single JSON-RPC byte crosses the wire.
Previously, whenever I discovered this happening with uvx/npx servers, I had worked around it by running a shared launchd/systemd HTTP MCP server on port 8766 (or whatever) so multiple sessions could talk to one long-lived Python/Node process. It stopped the lock contention, at the cost of yet another daemon to keep alive, another port to manage, and another config divergence between machines.
The cleaner fix was obvious: stop wrapping a localhost HTTP API in a Python runtime at all.
Enter joplin-mcp: a standalone, zero-runtime-dependency Rust MCP server for Joplin’s local Web Clipper / Data API.
1. The uvx Cache Stampede
uv and uvx are brilliant tools for Python packaging. Nobody misses managing virtualenv paths by hand.
But stdio MCP servers have an awkward lifecycle: the client spawns a fresh server process for every single session. That works fine when the binary starts in two milliseconds and touches nothing on disk. When the “command” is actually a package runner resolving environments and locking a shared cache directory, parallel agent workflows hit a wall:
- Cache lock contention: Three panes spawning
uvxsimultaneously race on theuvcache lock. Two sit blocked waiting for the first to finish checking metadata. - Cold-start overhead: Every new session pays Python interpreter startup and import time before answering
initialize. - Daemon drift: Moving to a shared
launchdorsystemdHTTP server on port8766solves the lock, but now you have a stateful background service instead of simplestdioplumbing.
What led to the idea was that I already had this pattern working successfully with my own Run MCP server (run --serve-mcp): drop one compiled Rust binary in ~/.local/bin, point the MCP config at it, and forget it exists. With joplin-mcp, I took that same pattern and made stdio MCP the entire binary.
Your MCP config collapses to four lines with zero arguments:
{
"mcpServers": {
"joplin-mcp": {
"command": "joplin-mcp"
}
}
}
2. Five Minutes, Not “Vibe-Coded”: Why Rust + Strict Hooks Works
From the first prompt to publishing v0.1.0 on crates.io, the entire project took roughly five minutes.
Mention a five-minute agentic build online and someone will immediately call it “vibe-coded” slop. In a loosely typed language, that criticism is often fair: an agent can sprint through a Python or Node prototype that passes one happy-path check while hiding silent Nones, swallowed exceptions, and tangled functions.
With Rust and an unforgiving verification harness from commit zero, you can’t really fail:
- Rust is built for agentic coding: The borrow checker, exhaustive
matcharms, and explicitResulttypes act as an impartial senior reviewer on every single edit. If an error path isn’t handled, it doesn’t compile. - Strict Clippy from the very first prompt:
Cargo.tomlenablesclippy::pedanticand denies bothunwrap_usedandexpect_used. - Pre-commit gates on every commit: A git pre-commit hook enforces
cargo fmt --all -- --check,cargo clippy --all-targets -- -D warnings, andcargo testbefore any commit can land.
When those guardrails are in place before a single line of application code exists, the agent cannot accumulate debt:
- No sloppy error paths: Denying
.unwrap()and.expect()forces properResultpropagation across every HTTP call, JSON parse, andstdioread from the start. - No argument bloat:
clippy::pedanticflags sprawling parameter lists (too_many_arguments) immediately, pushing the design towards clean option structs instead of 10-argument helper functions. - Immediate edge-case feedback: Formatting, warnings, and test regressions are rejected at every commit boundary rather than piled up for a painful cleanup pass later.
3. Zero-Config Profile Auto-Discovery
A good local CLI tool shouldn’t force you to copy-paste API tokens into every machine’s ~/.claude.json or agent config just to talk to localhost.
When JOPLIN_TOKEN (and JOPLIN_API_TOKEN) is unset, joplin-mcp automatically probes your local Joplin profiles in priority order:
- Joplin Desktop first (default port
41184): preferred when open because Desktop syncs faster through the Web Clipper service. joplin-clisecond (~/.config/joplin/settings.json, e.g. port41185running under asystemduser service): automatic fallback when Desktop is closed.
The client probes /folders?limit=1 with a two-second timeout, finds the active listener, and caches the resolved endpoint in memory. Even better: if a request fails because you closed Joplin Desktop and fell back to joplin-cli (or vice versa), joplin-mcp invalidates its cached endpoint and re-probes on the next call. No restarting your agent session just because you closed a window.
Keeping Tokens Out of Plaintext Configs
If you do pass an explicit token (for instance, talking to a specific port or remote tunnel), you still don’t have to leave secrets sitting in plaintext JSON files. Passing --token-cmd (or JOPLIN_TOKEN_CMD) runs a shell command and reads the token from stdout:
{
"mcpServers": {
"joplin-mcp": {
"command": "joplin-mcp",
"env": {
"JOPLIN_TOKEN_CMD": "security find-generic-password -a joplin -s joplin-web-clipper -w"
}
}
}
}
4. Safety by Default, Lean by Design
Giving an autonomous coding agent access to your personal knowledge base is only comfortable if the blast radius is bounded.
Out of the box, joplin-mcp exposes 22 tools covering ping, notebooks (list_notebooks, create_notebook, update_notebook), notes (get_note, get_note_resources, get_links, create_note, update_note, edit_note, find_notes, find_in_note, find_notes_with_tag, find_notes_in_notebook, get_all_notes), tags (list_tags, create_tag, update_tag, get_tags_by_note, tag_note, untag_note), and restore_from_trash.
Notice what is missing from that list: deletes.
delete_note, delete_notebook, and delete_tag are omitted from tools/list and rejected on tools/call unless you explicitly opt in with --allow-delete or JOPLIN_ALLOW_DELETE=true. An agent can organise, edit, and even restore from trash, without ever having permission to wipe a notebook on a bad prompt.
Under the hood, the entire binary stays lean:
- Five crates:
clap,regex,serde,serde_json, andureq. No async runtime, no Tokio thread pools, no heavy dependency tree. - Strict MCP handshake: Negotiates
protocolVersion(2024-11-05) cleanly overstdioJSON-RPC 2.0.
5. Before and After
Before (uvx + workaround):
Session 1: uvx joplin-mcp-server -> acquires uv cache lock, boots Python (~1.2s)
Session 2: uvx joplin-mcp-server -> blocks on uv cache lock
macOS fix: launchd HTTP daemon -> extra plist, port 8766, separate config
After (joplin-mcp in Rust):
Session 1: joplin-mcp -> instant binary start, auto-discovers 41184/41185
Session 2: joplin-mcp -> instant binary start, zero shared locks
Session 3: joplin-mcp -> instant binary start, zero daemons to babysit
No package runner contention. No Python runtime in the hot path. No hardcoded API tokens in ~/.claude.json. Just one binary that starts immediately and stays out of the way.
Available on crates.io (v0.1.0) and GitHub:
cargo install joplin-mcp