What the integration is
Joplin 3.7 added AI features. Joplin's news page says 3.7 includes a built-in MCP server that lets external tools work with your notes. That means an MCP-capable app such as Claude can read from and write to your Joplin data.
MCP is the Model Context Protocol, a standard way for AI apps to call tools. Joplin's help page says the server is off by default and exposes a small, fixed set of tools that you can switch on or off individually. Joplin never talks to a model itself. It only answers requests from whichever AI app you connect.
The author first used a community-built MCP server and later switched to Joplin's built-in one. He says the built-in server showed 11 tools in Claude Code and the community one showed 12, with sync being the extra one. That count is his observation, not a documented figure.
There are also third-party Joplin MCP projects for Claude Code, such as alondmnt's joplin-mcp. These are separate from Joplin's built-in server and have their own tool sets and install steps.
Setup
Joplin's MCP server runs on top of the Web Clipper service, so that service must be running. The steps from Joplin's documentation:
- Open Joplin's Configuration screen and go to Web Clipper. Start the service and note the port number and authorisation token.
- Go to the AI section and tick Enable MCP server.
- Open the Tools section and choose which tools to allow.
- Add the server to Claude Code.
The author's Claude Code command is:
claude mcp add --transport http --scope user joplin "[url]http://127.0.0.1:41184/mcp?token=YOUR_TOKEN[/url]"
Replace YOUR_TOKEN with the Web Clipper token. Joplin's documentation confirms the endpoint pattern, which is http://127.0.0.1:PORT/mcp?token=YOUR_TOKEN. Joplin says the server is HTTP-based and uses the same port as the Web Clipper. Check the actual port in your settings rather than assuming 41184.
Joplin's own page documents Claude Desktop, Cursor and Zed. It doesn't cover Claude Code specifically. The Claude Code command and its --scope user flag therefore come from the author alone. Joplin's guidance that Claude Desktop needs the mcp-remote bridge is specific to Claude Desktop, and the author's Claude Code command doesn't use one.
Troubleshooting
Joplin's documentation lists three common failures:
- Tools missing in the AI app. Most apps cache the tool list when they start. After you change a per-tool toggle, restart the AI app completely so it reconnects.
- Connection refused or 403. Check that the Web Clipper is started and the MCP toggle is on. The token in the URL must exactly match the one under Web Clipper.
- A write attempt says the tool isn't available. The write tool is off, or it was off when the app last connected. Turn it on and restart the AI app.
Semantic search
The author's biggest win was finding notes by meaning. He asked Claude Code to find notes about education and says it also surfaced notes about teaching. He reports sixteen notes, some of which he had forgotten. That count is his anecdote.
Joplin's documentation shows what has to be in place:
- Version and platform. Semantic search requires Joplin 3.7 or later. It works on Windows x64 and ARM64, Linux x64 and ARM64, and Apple Silicon Macs. It does not work on Intel Macs, mobile or the CLI.
- Local model. Joplin downloads a model of about 140 MB and runs it on your machine. Joplin says no note content goes to a cloud service for this indexing. The index isn't synced, so each device builds its own.
- Indexing time. Joplin processes 100 notes every five minutes. A 10,000-note vault takes roughly eight hours of background work. Edited notes are picked up within a few minutes after that first scan. If results look thin right after you enable it, the index may still be building. Progress shows under Settings → AI.
- Limits. Semantic search complements keyword search. It is weak for exact names, IDs and error codes, and a single-word query can return unrelated results, sometimes with high scores.
If you have Joplin 3.7 or later, the semantic search tool also needs the embeddings index to be enabled. Joplin turns on the embeddings indexer by default when you enable AI features.
Reorganising notes
The author asked Claude Code to audit his notebooks and propose a new hierarchy, including nested notebooks. He clarified a few points, approved the plan, and had it apply the changes and add tags. He says some untitled notes were filed correctly based on their content. He also says the job once took him a weekend and now takes minutes. These are his results, and the quality of the new structure is his judgment.
He also uses the connection to turn a week of meeting notes into an action list or report. He asks it to format reference-link notes into a chosen citation style. He pairs it with other tools such as Firecrawl and Lenz for citation checks and fact-checking. Joplin's documented tools (read, create, update, tag edits, notebook creation) cover this kind of work, but you should still review what an AI proposes and writes.
A correction on deletion
The author calls it a security feature that the built-in MCP doesn't delete notes or notebooks. That needs a correction.
Joplin's documentation lists a "Trash note" tool that moves a note to the trash. It is off by default but available. Joplin also warns that turning on write tools lets the AI app create, modify or trash notes. Joplin doesn't ask you to confirm each write, and the AI app may or may not. Joplin's advice is to leave write tools off unless you trust both the app and the model behind it.
The author may well have had the trash tool disabled, or Claude Code may have asked before acting. Either way, don't treat deletion as impossible. There is no documented notebook-delete tool, which fits his need to remove empty notebooks by hand.
A cautious path:
- Start with read-only tools: keyword search, semantic search, read note, list notebooks and list tags.
- Back up or export your notes before enabling any write tools.
- Enable write tools only for a specific task, such as the tag edits for a reorganisation.
- Leave Trash note off unless you need it.
- Read any proposed plan before approving it.
Privacy
Localhost doesn't mean your notes stay local. Joplin says the server listens only on 127.0.0.1, so other machines on your network can't reach it. The token guards against other applications on your own machine connecting without your knowledge.
But the connected AI app can read your notes. Joplin warns that its model may include note content in prompts sent to its own cloud provider. Joplin's own AI chat provider settings have no effect on what an external app does with that content.
Joplin's news post from 14 September 2026 says AI features are off by default, and it describes pointing Joplin's own chat at a local model such as Ollama or LM Studio. That applies to Joplin's chat. An external app like Claude Code follows its own provider's data handling. If your notes hold client data, HR material or anything regulated, check that policy before connecting. To switch the integration off, untick Enable MCP server or turn off the Web Clipper service.
Claude Code or Joplin's own chat?
Joplin 3.7 has its own chat panel for questions about the current note, summaries and edits, and it can use Joplin Cloud AI, your own OpenAI or Anthropic key, or a local model. The author still prefers Claude Code because he can attach other tools to it. That is his preference. Joplin's chat has a narrower privacy story, because it sends only the content a request needs. Claude Code is the stronger fit if you already use it with other tools.
Bottom line
Joplin's built-in MCP server is a documented, controllable way to let Claude Code search and reorganise a note vault, and semantic search is the most useful part. Enable only the tools you need, keep write access off at first, and remember that note content can reach your AI provider's cloud.