Joplin MCP Server

A Joplin plugin that exposes your notes as an MCP (Model Context Protocol) server. This allows AI assistants such as Claude Desktop, Cursor, VS Code Copilot, Kilo, and any other MCP-compatible client to create, read, update, and delete notes, notebooks, and tags, as well as search through your Joplin vault — directly through the standard MCP protocol.

Features

• Full note management — create, read, update, and delete notes (including to-dos)
• Notebook operations — list, create, rename, move, and delete notebooks with tree view
• Tag management — create, rename, delete tags; add/remove tags from notes
• Powerful search — search notes, notebooks, and tags using Joplin's built-in search engine with advanced query syntax
• 20 MCP tools covering all common note-taking operations
• Streamable HTTP transport — no stdio or local process required; works over HTTP
• Session management with automatic stale-session cleanup (30-minute TTL)
• Configurable — custom host and port settings within Joplin
• CORS support — works with browser-based clients and IDE extensions

Requirements

• Joplin >= 3.5
• An MCP-compatible client (Claude Desktop, Cursor, VS Code Copilot, Kilo, etc.)

Installation

From the Joplin Plugin Directory

1. Open Joplin
2. Go to Tools > Options > Plugins
3. Search for "MCP Server"
4. Click Install
5. Restart Joplin when prompted

Manually from Release

1. Download the latest net.hunnius.mcpserver.jpl file from the releases page
2. Open Joplin
3. Go to Tools > Options > Plugins
4. Click the gear icon and select Install from file
5. Select the downloaded .jpl file
6. Restart Joplin when prompted

Configuration

After installation, the MCP server starts automatically when Joplin launches. By default it listens on http://127.0.0.1:22123/mcp.

To change the host or port:

1. Open Joplin
2. Go to Tools > Options > MCP Server
3. Adjust the Port (default: 22123, range: 1024–65535)
4. Adjust the Host (default: 127.0.0.1)

Note: You must restart Joplin for changes to take effect.

MCP Client Setup

Configure your AI assistant to connect to the Joplin MCP server. The endpoint is:

http://127.0.0.1:22123/mcp

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp"
    }
  }
}

Claude Desktop / VS Code Copilot

Add to your mcp.json configuration file:

{
  "servers": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp",
      "type": "streamableHttp"
    }
  }
}

Kilo

Add to your kilo.json:

{
  "mcps": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp",
      "type": "streamableHttp"
    }
  }
}

Generic MCP Client

Any client supporting the Streamable HTTP transport can connect to http://127.0.0.1:22123/mcp. The server implements the standard MCP protocol with session management via the mcp-session-id header.

Available Tools

The plugin provides 20 MCP tools:

Notes

Tool	Description
create_note	Create a new note with optional title, body, notebook, to-do status, due date, and tags
get_note	Retrieve a specific note by ID, including full body, metadata, and tags
update_note	Update an existing note's title, body, notebook, to-do status, due date, or source URL
delete_note	Soft-delete a note (moved to trash)
list_notes	List notes with pagination, optional notebook filter, and sort options
get_notes_by_ids	Retrieve multiple notes by their IDs in a single call

Notebooks

Tool	Description
list_notebooks	List all notebooks as a tree hierarchy
get_notebook	Get notebook details including sub-notebooks and contained notes
create_notebook	Create a new notebook, optionally nested under a parent
update_notebook	Rename a notebook or move it to a different parent
delete_notebook	Soft-delete a notebook and all its notes

Tags

Tool	Description
list_tags	List all tags
create_tag	Create a new tag (returns existing if duplicate)
update_tag	Rename an existing tag
delete_tag	Permanently delete a tag (removed from all notes)
get_note_tags	List all tags assigned to a specific note
add_tag_to_note	Add a tag to a note (auto-creates the tag if it doesn't exist)
remove_tag_from_note	Remove a tag from a note

Search

Tool	Description
search_notes	Search notes using Joplin's query syntax (title:, body:, tag:, notebook:, -exclude, OR, etc.)
search_notebooks	Search notebooks by title
search_tags	Search tags by title
search_all	Search across notes, notebooks, and tags simultaneously

Utility

Tool	Description
ping	Test connectivity to the MCP server (returns pong)

Search Syntax

Joplin's search engine supports advanced queries:

Syntax	Description
word	Search for notes containing "word"
*	List all items
title:word	Search in note titles
body:word	Search in note bodies
tag:name	Search by tag
notebook:name	Search within a notebook
created:20240101	Filter by creation date
updated:20240101	Filter by update date
any:word1 word2	Match any of the words
-word	Exclude notes containing "word"
word1 OR word2	Match either word

Security Considerations

• Localhost by default — the server binds to 127.0.0.1, making it accessible only from the local machine
• CORS protection — only requests from localhost, 127.0.0.1, and vscode-webview:// origins are accepted from browsers; non-browser clients (like CLI tools) are allowed by default
• No authentication — the server does not require an API token or password. This is intentional for local-use simplicity. If you bind to 0.0.0.0, anyone on your network can access your Joplin data
• Network exposure — binding to 0.0.0.0 is supported for advanced use cases but should only be used on trusted, isolated networks

Development

Prerequisites

• Node.js >= 16
• npm

Build from Source

git clone https://codeberg.org/jhunnius/joplin-plugin-mcp.git
cd joplin-plugin-mcp
npm install
npm run dist

The built plugin is output to publish/net.hunnius.mcpserver.jpl.

Install Development Build

1. Build the plugin as described above
2. In Joplin, go to Tools > Options > Plugins
3. Click the gear icon and select Install from file
4. Select publish/net.hunnius.mcpserver.jpl

Project Structure

src/
├── index.ts    # Plugin entry point, settings registration
├── server.ts   # HTTP server, session management, CORS
└── tools.ts    # MCP tool definitions and handlers

License

MIT © Jan-Peter v. Hunnius

Links

• Repository: https://codeberg.org/jhunnius/joplin-plugin-mcp
• Issues: https://codeberg.org/jhunnius/joplin-plugin-mcp/issues
• Joplin: https://joplinapp.org/
• MCP Specification: https://modelcontextprotocol.io/