Skip to content
MCP server

Joplin MCP Server

Search, read, create, edit and sync Joplin notes and notebooks via a headless Joplin…

Runs locallyStatus and history
Install
Pricing
Open source
Runs
Locally
Version
2.3.3
Listing updated
4 days ago

About Joplin MCP Server

Joplin MCP Server is an open-source MCP server. It runs locally on your machine and is started by your AI client.

Search, read, create, edit and sync Joplin notes and notebooks via a headless Joplin sidecar.

Install

Run in a terminal

claude mcp add joplin-mcp-server --env JOPLIN_TOKEN='<JOPLIN_TOKEN>' --env JOPLIN_SYNC_PASSWORD='<JOPLIN_SYNC_PASSWORD>' -- npx -y joplin-mcp-server

Add to claude_desktop_config.json

{
  "mcpServers": {
    "joplin-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
        "JOPLIN_SYNC_PASSWORD": "<JOPLIN_SYNC_PASSWORD>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "joplin-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
        "JOPLIN_SYNC_PASSWORD": "<JOPLIN_SYNC_PASSWORD>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "joplin-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
        "JOPLIN_SYNC_PASSWORD": "<JOPLIN_SYNC_PASSWORD>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "joplin-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
        "JOPLIN_SYNC_PASSWORD": "<JOPLIN_SYNC_PASSWORD>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "joplin-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
        "JOPLIN_SYNC_PASSWORD": "<JOPLIN_SYNC_PASSWORD>"
      }
    }
  }
}

Configuration

  • JOPLIN_TOKENJoplin API token, for external mode only (see JOPLIN_HOST). Sidecar mode manages its own token and ignores this.
  • JOPLIN_HOSTConnect to an existing Joplin instance at this host instead of running a sidecar
  • JOPLIN_PORTPort of the existing Joplin instance (default: 41184)
  • JOPLIN_PROFILEJoplin data directory for sidecar mode (default: ~/.config/joplin-mcp)
  • JOPLIN_CLIPath to the joplin CLI binary, overriding auto-detection
  • JOPLIN_SYNC_TARGETSync target: none, filesystem, webdav, nextcloud, joplin-cloud, joplin-server, s3, dropbox, onedrive (default: none)
  • JOPLIN_SYNC_PATHSync target URL or path; the bucket name for the s3 target
  • JOPLIN_SYNC_USERNAMESync username or email; the access key for the s3 target
  • JOPLIN_SYNC_PASSWORDSync password; the secret key for the s3 target
  • JOPLIN_SYNC_REGIONS3 region (default: us-east-1)
  • JOPLIN_SYNC_ENDPOINTS3 endpoint URL for non-AWS providers such as Backblaze B2, MinIO, R2 or Wasabi (default: https://s3.amazonaws.com/)
  • JOPLIN_SYNC_FORCE_PATH_STYLEUse path-style S3 URLs, which self-hosted providers such as MinIO usually require: true or false (default: false)
  • LOG_LEVELLog verbosity: debug, info, warn or error (default: info)

Pricing

Open source

Joplin MCP Server FAQ

Is Joplin MCP Server free?

Yes. Joplin MCP Server is open source, so you can use and self-host it for free.

How do I add Joplin MCP Server to Claude Code?

Run this command in your terminal: claude mcp add joplin-mcp-server --env JOPLIN_TOKEN='<JOPLIN_TOKEN>' --env JOPLIN_SYNC_PASSWORD='<JOPLIN_SYNC_PASSWORD>' -- npx -y joplin-mcp-server