home / mcp / joplin mcp server

Joplin MCP Server

Provides a FastMCP-based interface to manage Joplin notes, notebooks, and tags via the Python API for AI assistants.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "alondmnt-joplin-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "joplin-mcp",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_HOST": "localhost",
        "JOPLIN_PORT": "41184",
        "JOPLIN_TOKEN": "YOUR_TOKEN_HERE",
        "JOPLIN_TIMEOUT": "30"
      }
    }
  }
}

You can run a FastMCP-based server that exposes Joplin data through a consistent API, letting AI assistants read, create, update, and organize notes, notebooks, and tags via the Joplin Python API. This server streamlines interactions with your Joplin data while offering configurable security and transport options.

How to use

Once the MCP server is running, connect your MCP-compatible AI client to it using one of the provided transport options. You can operate with a local (stdio) server, running commands directly on your machine, or you can run an HTTP transport that exposes the API over a web port. Practical tasks include listing notebooks, finding notes by text or tag, creating notes and tags, updating content, and importing files. The server exposes a rich set of tools to cover common note-taking workflows, including finding, creating, updating, tagging, and linking notes.

To get started quickly, ensure your client is configured with the correct MCP server endpoint, then issue natural language prompts or structured requests supported by your client. For example, you can ask to list notebooks, search notes about a topic, or tag a group of notes. The server enforces security levels so you can allow read-only access or enable create, update, or delete permissions as needed.

How to install

Prerequisites: Python is installed on your system. You may also use a zero-install tool runner such as uv to simplify setup. You will run one of several installation paths depending on your preferred client.

1) Install via Python package manager and start the server locally with a transport of your choice.

2) If you prefer an automated setup for Claude Desktop or similar clients, follow the cross‑tool installation steps outlined in the setup options to configure Joplin access and MCP server permissions.

Configuration and security

Configure access tokens and tool permissions to control what the AI can do. You can keep read access enabled by default and selectively enable write, update, and delete operations for notes, notebooks, and tags. You also control which actions the AI can perform through a tools configuration block.

Environment variables can be used to supply sensitive tokens, such as your Joplin API token. For example, you can provide your token via a JOPLIN_TOKEN variable when starting the server from a local CLI or within a container environment.

Troubleshooting and tips

If you encounter connectivity issues, verify the token and host settings, ensure the MCP service is listening on the expected port, and confirm the transport configuration matches your client. When running in HTTP mode, place the server behind a reverse proxy with TLS termination to protect traffic.

For development or testing, you can run the server with STDIO transport for local interaction, or run an HTTP transport to expose endpoints for browsing and testing from clients. Always restart your client after changing permissions or tokens.

Notes about usage patterns

Use search and filter capabilities to quickly locate notes, tags, or notebooks. Build workflows that create daily notes, tag groupings for projects, or organize notes by notebooks to reflect your personal structure.

Example usage reminders

Ask your AI to list notebooks, find notes with a specific tag, create a new note for a meeting, or tag recent notes with a chosen label. The server supports the full range of finding, creating, updating, deleting, and organizing content through the exposed tools.

Available tools

find_notes

Full-text search across notes with optional task filtering.

find_notes_with_tag

Find notes that contain a specific tag, with optional task filtering.

find_notes_in_notebook

Find notes within a specific notebook, with optional task filtering.

get_all_notes

Retrieve all notes, typically in reverse chronological order (disabled by default).

get_note

Retrieve a single note by its ID.

get_links

Extract links from a note to other notes.

create_note

Create a new note with content and metadata.

update_note

Update the content or metadata of an existing note.

delete_note

Delete a note permanently.

list_notebooks

List all notebooks for organization.

create_notebook

Create a new notebook.

update_notebook

Modify the title or properties of a notebook.

delete_notebook

Remove a notebook and its contents.

list_tags

List all available tags.

create_tag

Create a new tag.

update_tag

Modify an existing tag.

delete_tag

Delete a tag.

get_tags_by_note

List tags associated with a specific note.

tag_note

Add one or more tags to a note.

untag_note

Remove tags from a note.

import_from_file

Import files or directories (Markdown, HTML, CSV, TXT, JEX).

ping_joplin

Test connectivity to the Joplin API.