joplin-mcp-server

codetopolymath/joplin-mcp-server

3.2

If you are the rightful owner of joplin-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Joplin MCP Server connects Claude Desktop to Joplin for efficient note management using the Model Context Protocol.

Tools
10
Resources
0
Prompts
0

Joplin MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop to Joplin for seamless note management.

Features

šŸ“ Notes Management

  • Create, update, delete notes with Markdown content
  • Todo note support with completion tracking
  • Full-text search across all notes
  • Move notes between notebooks

šŸ“š Notebooks Management

  • Create notebooks and sub-notebooks
  • Update notebook properties
  • Browse notebook hierarchy

šŸ·ļø Tags Management

  • Create and manage tags
  • Add/remove tags from notes
  • Auto-creation when adding to notes

šŸ” Resource Access

  • Browse all notes as readable Markdown resources
  • List notebooks with full hierarchy
  • Search results as structured JSON

Quick Start

Prerequisites

  • Python 3.10+ with UV package manager
  • Joplin Desktop with API enabled
  • Claude Desktop application

1. Setup Project

git clone <repository-url> joplin-mcp-server
cd joplin-mcp-server
uv sync

2. Enable Joplin API

  1. Open Joplin Desktop
  2. Go to Tools ā†’ Options ā†’ Web Clipper
  3. Enable "Enable Web Clipper Service"
  4. Note the port (usually 41184) and copy the Authorization token

3. Configure Environment

Create .env file or set environment variables:

export JOPLIN_TOKEN="your_joplin_token_here"
export JOPLIN_PORT="41184"  # Optional: default is 41184

4. Test Setup

uv run python test_setup.py

Expected output:

šŸŽÆ Testing Joplin MCP Server Setup
āœ… Configuration successful!
āœ… Ping test successful!
āœ… API test successful!
šŸŽ‰ All tests passed!

Claude Desktop Configuration

Edit your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "joplin": {
      "command": "/full/path/to/uv",
      "args": [
        "--directory", "/absolute/path/to/joplin-mcp-server",
        "run", "python", "src/main.py"
      ],
      "env": {
        "JOPLIN_TOKEN": "your_joplin_token_here"
      }
    }
  }
}

Important Notes:

  • Use full path to uv (find with which uv)
  • Use absolute path to your project directory
  • Ensure Joplin Desktop is running before starting Claude Desktop
  • Restart Claude Desktop after configuration changes

Usage Examples

Reading Notes

"Show me all my notes"
"Read the note with ID abc123"
"What's in my 'Project Ideas' notebook?"
"Search for notes about 'machine learning'"

Creating Content

"Create a new note titled 'Meeting Notes' with today's agenda"
"Make a todo note for 'Buy groceries' in my Personal notebook"
"Create a notebook called 'Research'"

Organizing

"Move note xyz789 to the Projects notebook"
"Add tags 'important' and 'work' to my latest note"
"Mark the todo 'Finish report' as completed"

Available Resources

Read-only access via resource URIs:

  • joplin://notes/ - List all notes
  • joplin://notes/{note_id} - Read specific note as Markdown
  • joplin://notebooks/ - List all notebooks with hierarchy
  • joplin://search?q={query} - Search results

Available Tools

Write operations through tools:

Notes: create_note, update_note, delete_note, search_notes Notebooks: create_notebook, update_notebook, delete_notebook Tags: create_tag, add_tag_to_note, remove_tag_from_note

Troubleshooting

Common Issues

MCP Server Won't Connect (spawn uv ENOENT)

  • Use full UV path in config (find with which uv)
  • Common paths: /Users/username/.cargo/bin/uv, /opt/homebrew/bin/uv
  • Alternative: Use Python directly: "/path/to/.venv/bin/python" with args ["/path/to/src/main.py"]

Server Won't Start

  1. Ensure Joplin Desktop is running
  2. Verify API token is correct
  3. Check port 41184 is accessible
  4. Review server logs for specific errors

Claude Desktop Not Connecting

  1. Verify configuration file syntax
  2. Use absolute paths in configuration
  3. Check environment variables are set correctly
  4. Restart Claude Desktop after changes

Development

Project Structure

joplin-mcp-server/
ā”œā”€ā”€ pyproject.toml          # UV project configuration
ā”œā”€ā”€ src/
ā”‚   ā”œā”€ā”€ joplin_mcp/
ā”‚   ā”‚   ā”œā”€ā”€ server.py        # Main MCP server
ā”‚   ā”‚   ā”œā”€ā”€ config.py        # Configuration and discovery
ā”‚   ā”‚   ā”œā”€ā”€ joplin_client.py # Joplin REST API client
ā”‚   ā”‚   ā”œā”€ā”€ resources.py     # MCP Resources (read-only)
ā”‚   ā”‚   ā””ā”€ā”€ tools.py         # MCP Tools (write operations)
ā”‚   ā””ā”€ā”€ main.py              # Entry point
ā””ā”€ā”€ README.md

Adding Features

  1. New Tools: Add to tools.py and update tools list
  2. New Resources: Add to resources.py and update templates
  3. API Extensions: Extend joplin_client.py with new endpoints

Roadmap

Phase 1 (Current)

  • āœ… Notes CRUD operations
  • āœ… Basic notebook management
  • āœ… Tag operations
  • āœ… Search functionality

Phase 2 (Future)

  • Resource/attachment handling
  • Advanced search with filters
  • Real-time sync using Joplin events API
  • Bulk operations
  • Note templates and prompts

Phase 3 (Advanced)

  • Multiple Joplin instance support
  • Web clipper integration
  • Custom field support
  • Export/import operations

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

For issues:

  1. Check troubleshooting section
  2. Review Joplin's API documentation
  3. Check Claude Desktop MCP documentation
  4. Open an issue with detailed error logs

Happy note-taking with Claude and Joplin! šŸ“šŸ¤–