# Joplin MCP for Claude & ChatGPT

> Joplin MCP for Claude & ChatGPT is an open-source MCP server for ai models and llm tooling. Self-hosted MCP server giving Claude and ChatGPT controlled access to your Joplin notes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, Linux, Windows, macOS, self-hosted
- **Website:** https://joplin-mcp.romancello.net
- **Repository:** https://github.com/kogeler/joplin-md-sync
- **MCP Registry name:** io.github.kogeler/joplin-md-sync
- **Categories:** AI models and LLM tooling, knowledge and memory, developer tools
- **Listing updated:** 2026-11-18

## About

The README says this project connects AI assistants to a Joplin notebook that stays on your own server or desktop. Hosted Claude can sign in through a GitHub account via OAuth built into the server, while a private Custom GPT reaches notes through authenticated Actions. Local MCP clients can use stdio or Streamable HTTP instead.

The bridge talks to Joplin's local Data API and does not edit the Joplin database or sync target directly. Joplin remains the system of record, and the project offers an installer that sets up headless Joplin Terminal, recurrent sync and the adapter as Linux user services.

It also includes a Markdown workflow that pulls notebooks into files, shows three-way diffs and dry-run pushes before writing back, which suits people who want to review agent edits before they reach Joplin.

## Features

- **Hosted Claude sign-in:** Claude on claude.ai can connect through a GitHub login handled by the server itself, with no separate OAuth proxy.
- **Private Custom GPT access:** Authenticated Actions let a private ChatGPT Custom GPT search, read and change current Joplin notes.
- **Typed MCP tools:** Local stdio and Streamable HTTP transports expose structured note, notebook, tag and attachment operations.
- **Headless Linux installer:** A single installer deploys Joplin Terminal, recurrent sync and the adapter as rootless systemd services.
- **Reviewable Markdown sync:** Notebooks can be pulled to files, compared with three-way diffs and pushed after a dry run.
- **Explicit failure handling:** Duplicate creates return explicit errors and ambiguous write timeouts are reported rather than replayed.

## Good for

- Search and summarise your Joplin notes from Claude or a private ChatGPT GPT
- Save meeting follow-ups or decision records into a named Joplin notebook from a conversation
- Let a coding assistant read runbooks in Joplin and update targeted notes via MCP
- Keep Joplin notes reachable from assistants while the desktop app is closed, on a headless server
- Edit selected notebooks as Markdown files in Git and push reviewed changes back to Joplin

## Install

### Claude Code (Terminal)

```sh
claude mcp add joplin-md-sync --env JOPLIN_TOKEN='<JOPLIN_TOKEN>' -- uvx joplin-md-sync
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "joplin-md-sync": {
      "command": "uvx",
      "args": [
        "joplin-md-sync"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "joplin-md-sync": {
      "command": "uvx",
      "args": [
        "joplin-md-sync"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "joplin-md-sync": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "joplin-md-sync"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "joplin-md-sync": {
      "command": "uvx",
      "args": [
        "joplin-md-sync"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "joplin-md-sync": {
      "command": "uvx",
      "args": [
        "joplin-md-sync"
      ],
      "env": {
        "JOPLIN_TOKEN": "<JOPLIN_TOKEN>"
      }
    }
  }
}
```

## FAQ

### Does it need Joplin Desktop running?

The README says the headless installer runs Joplin Terminal as a service, so Joplin Desktop does not need to stay open. Running beside Joplin Desktop is also supported.

### Which storage backends are supported?

The README lists filesystem, Nextcloud, WebDAV, Dropbox, OneDrive, S3, Joplin Server and Joplin Cloud, with existing Joplin end-to-end encryption where the topology supports it.

### Is ChatGPT MCP supported yet?

Not yet. The README says a ChatGPT MCP connector through the same built-in OAuth is planned, and that private Custom GPTs currently work through Actions.

### What is the licence?

The README states the project is MIT licensed and is not affiliated with the Joplin project.

### Is Joplin MCP for Claude & ChatGPT free?

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

### How do I add Joplin MCP for Claude & ChatGPT to Claude Code?

Run this command in your terminal: claude mcp add joplin-md-sync --env JOPLIN_TOKEN='<JOPLIN_TOKEN>' -- uvx joplin-md-sync

### What are the best alternatives to Joplin MCP for Claude & ChatGPT?

The closest alternatives to Joplin MCP for Claude & ChatGPT are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Where this comes from

- Description: written from the project's README, the project's website and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/joplin-mcp-for-claude-and-chatgpt
