joplin

This MCP server exposes a comprehensive set of tools for interacting with Joplin via its Python API (joppy). It provides 24 tools organized into note, notebook, and tag management, as well as import and system health capabilities. You can query and manipulate notes, notebooks, tags, and links; search and filter notes; create, update, or delete content; and import data from files. To use it with your AI assistant, point your MCP client (Claude Desktop, Claude Code, Jan AI, or OllMCP) at the server, supplying your JOPLIN_TOKEN for authentication. The server uses the standard MCP protocol so compatible clients can discover and call these tools through a consistent interface.

Once configured, you can perform common operations like listing notebooks, finding notes by text or tag, creating new notes, updating note content, tagging notes, and importing content from Markdown or other supported formats. For interactive work, you can request actions such as creating a meeting note, tagging recent notes, or listing notes with particular properties, all through natural-language prompts that map to the underlying MCP tools.

Prerequisites:

• Joplin desktop or server API enabled (Web Clipper/token configured).
• Python environment and pip, or uvx installed for zero-install execution.
• Access to install or run uvx (Zero-install) or an equivalent execution method.

Step-by-step installation:

1. Install the MCP client runtime (uvx) if you don’t already have it:
   • Install uv: pip install uv
   • Install the MCP runner via uvx later when configuring the server
2. Install or prepare the joplin-mcp package/microservice as described in the documentation for your setup (e.g., using uvx):
   • uvx --from joplin-mcp joplin-mcp-install
   • If you prefer a direct install, follow the traditional pip install joplin-mcp and run joplin-mcp-install
3. Obtain your Joplin API token from Joplin (Tools > Options > Web Clipper) and set it as an environment variable JOPLIN_TOKEN during configuration
4. Configure your MCP client (Claude Desktop, Jan AI, OllMCP) to point to the server using the command and environment shown in the mcp_config snippet, or use the provided configuration examples in claude_desktop_config.json or ollmcp examples
5. Start the MCP server and verify connectivity by issuing a simple tool call like list_notebooks or ping_joplin

Notes and tips:

• Requires JOPLIN_TOKEN in environment variables for authentication with the Joplin API.
• If you use uvx (zero-install), ensure uv and Python are available in the host environment; uvx will handle running the Python-based MCP server without a full installation.
• For Jan AI and other clients, you may configure environment variables and the server command in their MCP settings; the token must be provided to the server to access Joplin resources.
• If you run into SSL or connectivity issues, you can adjust verify_ssl in the client configuration or the server config to disable SSL verification where appropriate (not recommended for production).
• The tool set includes note, notebook, and tag management, plus import and health checks; consult the Complete Tool Reference in the README for exact tool names and usage patterns.