Joplin Server MCP

Model Context Protocol server for Joplin Server. Gives LLMs full access to your notes, notebooks, tags, and attachments via the Joplin Server REST API.

What is Joplin Server?

Joplin is an open-source note-taking app with Markdown support, end-to-end encryption, and sync across devices. Joplin Server is the sync backend that stores and syncs your data. You can run it yourself using the official Docker image or use the managed Joplin Cloud service.

Note: This MCP server connects to Joplin Server REST API, not the Joplin Desktop Web Clipper.

Joplin Cloud: Should work with JOPLIN_SERVER_URL=https://joplincloud.com, but this has not been tested. If you try it — please open an issue with your results.

Related MCP server: joplin-mcp

Tools

Setup

Prerequisites

• A running Joplin Server instance or Joplin Cloud account

• User credentials (email + password)

Environment variables

Run with Docker

docker run -d \
  -e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
  -e JOPLIN_EMAIL=your@email.com \
  -e JOPLIN_PASSWORD=your_password \
  -p 8081:8081 \
  alexfail2/joplin-mcp

The container defaults to SSE transport. The endpoint will be available at http://localhost:8081/sse.

Run locally (stdio)

pip install mcp httpx
python app/server.py

Build from source

docker build -t joplin-mcp .

MCP client configuration

SSE (Docker)

{
  "mcpServers": {
    "joplin": {
      "url": "http://localhost:8081/sse"
    }
  }
}

stdio (local)

{
  "mcpServers": {
    "joplin": {
      "command": "python",
      "args": ["/path/to/app/server.py"],
      "env": {
        "JOPLIN_SERVER_URL": "https://your-joplin-server.example.com",
        "JOPLIN_EMAIL": "your@email.com",
        "JOPLIN_PASSWORD": "your_password"
      }
    }
  }
}

How it works

The server authenticates with Joplin Server via email/password sessions and builds an in-memory index of all items (notes, notebooks, tags) with a 2-minute TTL cache. Incremental sync compares server-side updated_time with cached etags, fetching only changed items (typical refresh: ~5s vs ~35s full rebuild). The index is persisted to disk so container restarts are instant. Resource metadata is loaded lazily on first access. Background refresh keeps the index up to date without blocking requests. All IDs are validated (32-char hex) before API calls.

Joplin's internal serialization format (title + markdown body + metadata block) is parsed and presented as clean structured output.

License

MIT