# Joplin MCP Server

Connect an AI assistant to Joplin to search and edit notes, manage tags, and import files. You’ll need a Joplin API token to configure access.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 174
- Author: alondmnt
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/alondmnt/joplin-mcp
- Updated: 2026-09-12
- HTML: https://affpapa.org/en/nevibecode/mcp/joplin-mcp-server

## What it does

This MCP server lets an AI assistant work with Joplin notes, notebooks, and tags. It can find and edit notes, create entries, and restore items from the trash. For attached images and PDFs, it can retrieve OCR text.

The server also imports Markdown, HTML, CSV, TXT, and JEX files, as well as directories. You can limit access to selected notebooks with path patterns, including nested notebooks and exclusions. Read, write, update, and delete permissions can be configured separately. Joplin’s Web Clipper service must be enabled, and its API token is required for the connection.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `JOPLIN_TOKEN`, `JOPLIN_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_URL=<JOPLIN_URL> --transport stdio joplin-mcp-server -- uvx joplin-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add joplin-mcp-server --env JOPLIN_TOKEN=<JOPLIN_TOKEN> --env JOPLIN_URL=<JOPLIN_URL> -- uvx joplin-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "joplin-mcp-server": {
            "command": "uvx",
            "args": [
                "joplin-mcp"
            ],
            "env": {
                "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
                "JOPLIN_URL": "<JOPLIN_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "joplin-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "joplin-mcp"
            ],
            "env": {
                "JOPLIN_TOKEN": "<JOPLIN_TOKEN>",
                "JOPLIN_URL": "<JOPLIN_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e JOPLIN_TOKEN=<JOPLIN_TOKEN> -e JOPLIN_URL=<JOPLIN_URL> joplin-mcp-server uvx joplin-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from joplin-mcp <command>

## When to use it
- search Joplin notes by topic or tag
- create notes in a chosen notebook
- organize entries with tags
- import Markdown or CSV files into Joplin
- restrict assistant access to selected notebooks

## Example prompts
- Find my Joplin notes about Python and show the relevant ones.
- Create a note about today’s meeting in the Work notebook.
- Import `notes.md` into Joplin and tag the new note as important.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md