Riventh/joplin-desktop-mcp

Joplin MCP Server

A standalone Model Context Protocol (MCP) server for Joplin Desktop that enables AI assistants like Claude to interact with your Joplin notes, notebooks, and tags.

Architecture

This is a standalone MCP server that communicates with Joplin Desktop through the Web Clipper API. It does not require a Joplin plugin installation.

Features

Note Management

• Find & Search

  • find_notes - Search for notes by query string
  • find_notes_with_tag - Find notes with a specific tag
  • find_notes_in_notebook - Find notes in a specific notebook
  • get_all_notes - Get all notes in Joplin

• CRUD Operations

  • get_note - Get a specific note with full content
  • get_links - Extract all internal and external links from a note
  • create_note - Create a new note (with optional tags)
  • update_note - Update an existing note
  • delete_note - Delete a note

Notebook Management

• list_notebooks - List all notebooks
• create_notebook - Create a new notebook (supports sub-notebooks)
• update_notebook - Update notebook properties
• delete_notebook - Delete a notebook

Tag Management

• list_tags - List all tags
• create_tag - Create a new tag
• update_tag - Update a tag's title
• delete_tag - Delete a tag
• get_tags_by_note - Get all tags for a specific note
• tag_note - Add a tag to a note
• untag_note - Remove a tag from a note

Prerequisites

1. Joplin Desktop must be running
2. Web Clipper service must be enabled in Joplin:
   • Go to Tools > Options > Web Clipper
   • Enable "Enable Web Clipper Service"
   • Note the port (default: 41184)
   • Copy the "Authorization token"

Installation

1. Clone and Build

git clone <repository-url>
cd mcp-joplin-desktop
npm install
npm run build:standalone

This creates dist-standalone/standalone-server.js

2. Get Your Joplin Token

From Joplin Desktop:

1. Go to Tools > Options > Web Clipper
2. Copy the Authorization token (long string)

3. Configure Environment

Set your Joplin token as an environment variable:

export JOPLIN_TOKEN="your-token-here"
export JOPLIN_PORT="41184"  # Optional, defaults to 41184

Add these to your ~/.bashrc or ~/.zshrc to persist across sessions.

4. Add to Claude Code

Run this command:

claude mcp add --transport stdio --scope user joplin -- node /path/to/mcp-joplin-desktop/dist-standalone/standalone-server.js

Or use the wrapper script:

chmod +x start-joplin-mcp.sh
claude mcp add --transport stdio --scope user joplin -- /path/to/mcp-joplin-desktop/start-joplin-mcp.sh

5. Verify

claude mcp list

You should see joplin in the list.

Usage

With Claude Code

In Claude Code, the Joplin tools are automatically available. You can:

List all my notebooks
Create a note titled "Meeting Notes" in the "Work" notebook
Search for notes about "project planning"

Tool Examples

Create a Note

{
  "tool": "create_note",
  "arguments": {
    "title": "My New Note",
    "body": "This is the content of my note",
    "parent_id": "notebook-id-here",
    "tags": ["tag-id-1", "tag-id-2"]
  }
}

Search for Notes

{
  "tool": "find_notes",
  "arguments": {
    "query": "meeting notes",
    "limit": 10
  }
}

Get Note Links

{
  "tool": "get_links",
  "arguments": {
    "noteId": "note-id-here"
  }
}

Returns:

{
  "noteId": "note-id",
  "noteTitle": "Note Title",
  "links": [
    {
      "text": "Internal Link",
      "url": ":/note-id",
      "type": "internal"
    },
    {
      "text": "External Link",
      "url": "https://example.com",
      "type": "external"
    }
  ]
}

Development

Project Structure

mcp-joplin-desktop/
├── standalone-server.ts      # Main standalone server
├── start-joplin-mcp.sh       # Wrapper script with env vars
├── STANDALONE-SETUP.md       # Detailed setup guide
├── package.json
└── dist-standalone/          # Built server (after npm run build:standalone)
    └── standalone-server.js

Building

npm run build:standalone

Testing

Run the server directly:

export JOPLIN_TOKEN="your-token"
npm run start:standalone

Test the Joplin API directly:

curl "http://localhost:41184/notes?token=YOUR_TOKEN_HERE"

Troubleshooting

Server won't start

• Make sure Joplin Desktop is running
• Verify Web Clipper service is enabled in Joplin settings
• Check that JOPLIN_TOKEN environment variable is set correctly

Connection errors

• Verify the port (default 41184) in Joplin settings
• If using a different port, set JOPLIN_PORT environment variable
• Check firewall settings aren't blocking localhost connections

Token issues

• Get a fresh token from Joplin: Tools > Options > Web Clipper
• Make sure there are no extra spaces when copying the token
• Token should be a long alphanumeric string

API Reference

All tools return JSON responses. Most operations return the full object (note, notebook, or tag) with its properties.

Common Response Fields

Notes:

• id: Unique identifier
• title: Note title
• body: Note content (markdown)
• parent_id: Parent notebook ID
• created_time: Creation timestamp
• updated_time: Last update timestamp

Notebooks:

• id: Unique identifier
• title: Notebook title
• parent_id: Parent notebook ID (for sub-notebooks)
• created_time: Creation timestamp
• updated_time: Last update timestamp

Tags:

• id: Unique identifier
• title: Tag title
• created_time: Creation timestamp
• updated_time: Last update timestamp

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Acknowledgments

Built using:

• Joplin Web Clipper API
• Model Context Protocol SDK

Support

For issues and questions:

• Joplin Forum: https://discourse.joplinapp.org/