Joplin

You run an MCP server that connects Joplin notes to AI clients, enabling search, reading, creation, deletion, moving, and listing notes and notebooks through Joplin's Web Clipper API. This makes it easy to manage your notes from AI tools while keeping your data in Joplin.

How to use

Connect an MCP client to your Joplin MCP server, then use the available tools to search, read, create, delete, move, and list notes and notebooks. You can target specific notebooks, gather complete note contents, and manage your notes from conversational prompts in supported AI clients. The server auto-detects the Joplin Web Clipper port and uses your API token for authentication.

How to install

Prerequisites you need to install and run the MCP Joplin Server:

1. Joplin Desktop is installed and running

2. Node.js 18+

3. Web Clipper enabled in Joplin

Configuration and runtime

Enable and configure the Joplin Web Clipper service in Joplin, then start the MCP server using one of the explicit commands shown.

# Example 1: path-based config from the JSON snippet
{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

# Example 2: Claude Desktop config style
{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

If you prefer running locally without a JSON config, you can start the MCP server directly using npm. The server will auto-detect the Joplin Web Clipper port (usually 41184) and will use your token if provided.

Security and tokens

This MCP server requires a Joplin Web Clipper API token to function properly. Keep your token secure and pass it to the server startup command when required.

Troubleshooting

If you run into connection issues, verify the following steps:

• Joplin is running and the Web Clipper service is enabled

• The Web Clipper port matches what you configured (default 41184)

• Your API token, if used, is correct

Notes on the environment and startup

Environment variables shown in examples are optional placeholders. If you use a token, replace YOUR_API_TOKEN with your real API token.

Tools and capabilities

The server exposes a set of tools to interact with your Joplin data. These tools include getting the complete content of a note, searching notes and notebooks, listing notebooks and notes, creating and deleting notes and notebooks, moving notes, and scanning for unchecked todo items.

Security and API token usage details

To ensure secure access, an API token is required for some configurations. Include the token in startup commands or in the client’s configuration as shown in the examples.

Development

Development-related commands are available for building and running in development mode if you need to customize the MCP Joplin server further.

Technical architecture

Language: TypeScript/Node.js. MCP SDK: @modelcontextprotocol/sdk. HTTP client: axios. CLI: commander. API: Joplin Web Clipper API.

License and support

MIT License. If you encounter problems, check that Joplin Web Clipper is running, review error messages, and provide detailed error information when seeking help.

Available tools

get_note_content

Retrieve the complete content of a specific note by its ID.

search_notes

Search notes by a query string with an optional limit on results.

search_notebooks

Search notebooks by a query string.

list_notebooks

List all notebooks.

list_notes

List notes within a specific notebook with optional limit.

list_sub_notebooks

List sub-notebooks under a specific notebook.

create_note

Create a new note with a title, body, and optional target notebook.

create_notebook

Create a new notebook with a title and optional parent notebook.

delete_note

Delete a note by ID, with an option for permanent deletion.

delete_notebook

Delete a notebook by ID, with an option for permanent deletion.

move_note

Move a note to a different notebook.

scan_unchecked_items

Scan for unchecked todo items within a notebook and sub-notebooks.