Joplin MCP Service

A Model Context Protocol (MCP) 1.0 service that provides essential read/write tools for Joplin integration, enabling agentic systems to interact with Joplin notes, folders, and tags.

Features

The Joplin MCP Service provides 19 tools organized by entity type for comprehensive Joplin integration.

Note Tools (9 tools)

Search & Query:

• joplinSearchNotes - Full-text search across all notes
• joplinGetNotesByDateRange - Retrieve notes within date range
• joplinGetNotesByFolders - Get notes from specific folders
• joplinGetNotesByTags - Get notes with specific tags
• joplinGetNoteContent - Retrieve full note details

CRUD Operations:

• joplinCreateNote - Create new notes
• joplinUpdateNote - Update existing notes
• joplinDeleteNote - Delete notes

Tagging:

• joplinTagNote - Add/remove tags from notes (auto-creates tags)

Folder Tools (4 tools)

• joplinListFolders - List all available folders/notebooks
• joplinCreateFolder - Create new folders/notebooks
• joplinUpdateFolder - Rename or move folders
• joplinDeleteFolder - Delete folders (and all contained notes)

Tag Tools (4 tools)

• joplinListTags - List all available tags
• joplinCreateTag - Create new tags (idempotent)
• joplinUpdateTag - Rename tags
• joplinDeleteTag - Delete tags (removes from all notes)

Utility Tools (2 tools)

• joplinHealthCheck - Verify service and Joplin connectivity
• joplinGetNoteRelationships - Get note's tags and folder info

Installation

Global Installation

# Install the package globally
npm install -g joplin-mcp-service

# Verify installation
joplin-mcp --help

Development Installation

git clone <repository-url>
cd joplin-mcp-service
npm install
npm run build

Configuration

The service supports multiple configuration methods (in order of precedence):

1. Environment Variable

export JOPLIN_TOKEN="your-joplin-token-here"

2. Configuration File

Create ~/.joplin-mcp/config.json:

{
  "joplin": {
    "token": "your-joplin-token-here",
    "baseUrl": "http://127.0.0.1:41184"
  }
}

3. Token File

Create .joplin_token in your working directory with your Joplin API token.

Getting Your Joplin Token

1. Open Joplin
2. Go to Tools > Options > Web Clipper
3. Enable the Web Clipper service
4. Copy the API token from the Web Clipper settings

Usage

With MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Start inspector with Joplin service
mcp-inspector joplin-mcp

With Cursor

Create ~/.cursor/mcp.json (or C:\Users\[username]\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp",
      "args": [],
      "env": {
        "JOPLIN_TOKEN": "your-joplin-token-here"
      }
    }
  }
}

Alternative Configuration: Use the global config file instead of environment variables:

1. Create ~/.joplin-mcp/config.json with your token
2. Use this simpler Cursor configuration:

{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp",
      "args": []
    }
  }
}

Tool Examples

Search Notes

{
  "name": "joplinSearchNotes",
  "arguments": {
    "query": "meeting notes",
    "limit": 10
  }
}

Create Note

{
  "name": "joplinCreateNote",
  "arguments": {
    "title": "New Note",
    "body": "Note content here",
    "parentId": "folder-id-optional"
  }
}

Get Notes by Date Range

{
  "name": "joplinGetNotesByDateRange",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "dateField": "updated_time"
  }
}

Tag Notes

{
  "name": "joplinTagNote",
  "arguments": {
    "noteId": "abc123",
    "tagNames": ["python", "curriculum"],
    "action": "add"
  }
}

Create Folder

{
  "name": "joplinCreateFolder",
  "arguments": {
    "title": "My New Notebook",
    "parentId": "parent-folder-id-optional"
  }
}

Requirements

• Node.js 16.0.0 or higher
• Joplin running with Web Clipper enabled
• Valid Joplin API token

Development

Building

npm run build

Development Mode

npm run dev

Project Structure

joplin-mcp-service/
├── src/
│   ├── index.ts              # Main service entry point
│   ├── joplin-client.ts      # Joplin API client
│   ├── config.ts             # Configuration management
│   ├── types.ts              # TypeScript type definitions
│   └── tools/                # MCP tool implementations (entity-based)
│       ├── index.ts          # Tool aggregator
│       ├── note-tools.ts     # Note operations (9 tools)
│       ├── folder-tools.ts   # Folder operations (4 tools)
│       ├── tag-tools.ts      # Tag operations (4 tools)
│       └── utility-tools.ts  # Utility operations (2 tools)
├── design/
│   ├── joplin-mcp-improvements-prd.md  # Product requirements
│   └── write-tools-status.md           # Implementation status
├── examples/
│   ├── mcp.json              # Cursor MCP configuration
│   └── inspector-example.md  # MCP Inspector usage
└── dist/                     # Compiled JavaScript (after build)

Key Features

Entity-Based Architecture

Tools are organized by entity type (Notes, Folders, Tags) rather than operation type (read/write) for better maintainability and discoverability. All operations for a specific entity are grouped together.

Auto-Creating Tags

When adding tags to notes using joplinTagNote, tags that don't exist will be automatically created. This streamlines the workflow and matches Joplin UI behavior.

Idempotent Operations

• Tag Creation: Calling joplinCreateTag with an existing tag name returns the existing tag instead of erroring
• Tag Addition: Adding a tag that's already on a note is handled gracefully

Complete CRUD Operations

Full create, read, update, delete support for all three main entities:

• Notes: Search, query, create, update, delete, tag
• Folders: List, create, update (rename/move), delete
• Tags: List, create, update (rename), delete

Troubleshooting

Common Issues

1. "No Joplin token found"

   • Ensure you have set up authentication using one of the methods above
   • Verify your token is valid

2. "Failed to connect to Joplin"

   • Ensure Joplin is running
   • Check that Web Clipper is enabled
   • Verify the base URL (default: http://127.0.0.1:41184)

3. Tool execution errors

   • Check the console output for detailed error messages
   • Verify your Joplin data is accessible
   • Ensure you have the necessary permissions

Debug Mode

Set NODE_ENV=development for additional logging:

NODE_ENV=development joplin-mcp

License

ISC

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section
2. Review the examples
3. Open an issue on GitHub