joplin

Joplin MCP — Orchestration Guide

This skill covers non-obvious tool interactions. Tool parameters are already in the tool schemas — don't restate them here.

Setup

If Joplin MCP tools (e.g., ping_joplin) aren't available, the server isn't connected. Follow these steps to configure it automatically:

1. Ask the user for their Joplin API token. Tell them where to find it:

   Open Joplin Desktop → Tools → Options → Web Clipper → copy the Authorization token.

2. Write .mcp.json to the project root with the token. Use the Write tool to create the file:

   {
     "mcpServers": {
       "joplin-mcp": {
         "command": "uvx",
         "args": ["--from", "joplin-mcp", "joplin-mcp-server"],
         "env": {
           "JOPLIN_TOKEN": "<paste_token_here>"
         }
       }
     }
   }
   

   This file is already covered by .gitignore (.* rule) so it won't be committed.

3. Tell the user to restart Claude Code. The MCP server is loaded at startup, so a restart is required for the tools to appear.

4. After restart, call ping_joplin to verify the connection.

Critical: edit_note vs update_note

• edit_note — find/replace, append, prepend. Use this for partial changes.
• update_note(body=...) — replaces the entire body. Only use when you intend to rewrite the whole note.

If you need to change a paragraph, fix a typo, or append a section: always use edit_note.

Reading long notes

get_note returns a table of contents (not content) when a note exceeds ~50 lines. To read the actual content:

1. get_note(note_id) — see the TOC and line count
2. get_note(note_id, section="Section Name") — extract a specific section
3. get_note(note_id, start_line=1, line_count=50) — sequential reading by line range
4. get_note(note_id, force_full=True) — force full content (large context cost)

IDs vs names