Joplin Mcp

joplin-mcp

A Go-based MCP server that connects AI assistants to Joplin desktop for complete note management.

Features

27 tools covering notes, folders, tags, search, batch operations, export/import, and resource management — all accessible to any MCP-compatible AI assistant (Claude, etc.).

• Notes: create, read, update, delete, batch-read
• Search: full-text search with body previews
• Folders: list, create, rename, delete (nested tree with computed paths)
• Tags: list, apply, remove, delete, query notes by tag
• Batch: move notes, tag/untag in bulk, merge notes
• Export/Import: export to Markdown files, bulk import from directory
• Resources: list, inspect, download, and upload attachments
• Utility: connectivity check, import single Markdown file

Prerequisites

• Joplin desktop installed and running
• Web Clipper enabled: Settings → Web Clipper → Enable Web Clipper Service
• Copy your API token from the Web Clipper settings page

Installation

Homebrew

brew tap wickes1/tap
brew install joplin-mcp

Go

go install github.com/Wickes1/joplin-mcp@latest

Binary

Download pre-built binaries from GitHub Releases.

Available for: macOS (Intel/Apple Silicon), Linux (x8664/arm64), Windows (x8664/arm64).

Configuration

Add to your .mcp.json (or Claude Code's MCP config):

{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp",
      "env": {
        "JOPLIN_TOKEN": "your-token-here",
        "JOPLIN_HOST": "localhost",
        "JOPLIN_PORT": "41184"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | JOPLIN_TOKEN | (required) | Joplin Web Clipper API token | | JOPLIN_HOST | localhost | Joplin API host | | JOPLIN_PORT | 41184 | Joplin API port | | JOPLIN_LOG_LEVEL | info | Log level: debug, info, warn, error | | JOPLIN_READ_TIMEOUT | 30 | Per-request timeout in seconds for GET operations | | JOPLIN_WRITE_TIMEOUT | 120 | Per-request timeout in seconds for POST/PUT/DELETE operations |

> Security: Do not commit JOPLIN_TOKEN to version control. On macOS, store it in Keychain and inject it via a wrapper script.

Tools Reference

Notes (6 tools)

| Tool | Description | |------|-------------| | list_notes | List notes, optionally filtered by folder. Returns slim notes and a has_more flag. | | get_note | Get a single note by ID with full body and tags. | | get_notes | Batch-read up to 50 notes by ID. Failed lookups are included as error entries. | | create_note | Create a new note. Optionally auto-create folder by name and apply tags. | | update_note | Update an existing note's title, body, folder, or to-do status. folder_name auto-creates if not found. | | delete_note | Delete a note by ID. By default moves to trash; set permanent=true to bypass trash. |

Search (1 tool)

| Tool | Description | |------|-------------| | search_notes | Full-text search across all notes. Returns preview notes (200-char body preview) and a has_more flag. |

Folders (4 tools)

| Tool | Description | |------|-------------| | list_folders | List all folders as a nested tree with computed paths (e.g. Work/Projects/Q1). | | create_folder | Create a new folder, optionally nested under a parent folder. | | update_folder | Rename or move a folder. | | delete_folder | Delete a folder by ID. By default moves to trash; set permanent=true to bypass trash. |

Tags (5 tools)

| Tool | Description | |------|-------------| | list_tags | List all tags in the Joplin library. | | tag_note | Apply a tag to a note. Creates the tag if it does not exist (case-insensitive). | | untag_note | Remove a tag from a note (case-insensitive tag lookup). | | delete_tag | Delete a tag by ID. Removes it from all notes. | | get_notes_by_tag | Get notes associated with a tag name (case-insensitive). Returns slim notes and a has_more flag. |

Batch (3 tools)

| Tool | Description | |------|-------------| | batch_move_notes | Move up to 100 notes to a destination folder concurrently. | | batch_tag_notes | Add or remove a tag from up to 100 notes concurrently. Creates the tag automatically when adding. | | merge_notes | Fetch up to 50 notes, concatenate their bodies with headings and separators, create a new merged note. |

Export / Import (2 tools)

| Tool | Description | |------|-------------| | export_notes | Export Joplin notes to the filesystem as Markdown files, preserving folder hierarchy with optional YAML frontmatter. | | batch_import_markdown | Walk a directory for .md files and import each as a Joplin note, optionally preserving directory structure as folders. |

Resources (4 tools)

| Tool | Description | |------|-------------| | list_resources | List Joplin resources (attachments). Returns a page of resources and a has_more flag. | | get_resource | Get metadata for a single Joplin resource (attachment) by ID. | | download_resource | Download a Joplin resource (attachment) file to a local path on disk. | | upload_resource | Upload a local file as a Joplin resource. Returns an ID for embedding: ` or [name](:/id)`. |

Utility (2 tools)

| Tool | Description | |------|-------------| | import_markdown | Import a single Markdown (.md) file into Joplin as a note. Title extracted from the first # heading or filename. | | get_status | Check Joplin connectivity and return library statistics (folder count, tag count, port). |

Response Design

Tools follow a slim / full / preview pattern to keep token usage low:

• Slim (list operations): id, title, parent_id, folder_title, is_todo, updated_time. Used for browsing without fetching note bodies.
• Full (getnote, getnotes): All slim fields plus body, created_time, todo_completed, and tags[]. Used when content is needed.
• Preview (search): Slim fields plus the first 200 characters of the body. Usually enough to judge relevance without a follow-up get_note call.

Write operations (create_note, update_note, etc.) return slim responses; read operations (get_note, get_notes) return full responses.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wickes1
• Source: wickes1/joplin-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.