joplin-connect

Claude Code skills and MCP server for managing Joplin notes, notebooks, tags, resources, and search — all from your terminal.

Two integration approaches are provided:

| Approach | How it works | Best for | |----------|-------------|----------| | Skills (recommended) | Markdown prompts that teach Claude Code to call Joplin's REST API via curl | Zero dependencies, easy to read and customize | | MCP Server | A TypeScript MCP server that exposes Joplin operations as tools | Structured tool calls, reusable across MCP-compatible clients |

Prerequisites

Joplin desktop app installed and running
Web Clipper service enabled: Joplin → Tools → Options → Web Clipper → Enable Web Clipper Service
API token: found at Tools → Options → Web Clipper → Advanced options → API token
Claude Code CLI installed

Setup

Set your Joplin API token

Add to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export JOPLIN_TOKEN="your_api_token_here"

Or configure it in .claude/settings.local.json:

{
  "env": {
    "JOPLIN_TOKEN": "your_api_token_here"
  }
}

Joplin listens on port 41184 by default. Set JOPLIN_PORT if yours differs.

Option A: Skills

Copy the skill folders into your project's .claude/skills/ directory:

# From this repo's root
cp -r skills/* /path/to/your/project/.claude/skills/

Then use them in Claude Code:

> /joplin create a note titled "Hello" in the Work notebook
> /joplin-search find notes tagged "important"

Available Skills

| Skill | Description | |-------|-------------| | joplin | Main entry point — routes requests to sub-skills, handles direct queries | | joplin-create-note | Create, update, and delete notes | | joplin-search | Search notes, notebooks, and tags with Joplin's query syntax | | joplin-manage-notebooks | Create, list, rename, move, and delete notebooks | | joplin-manage-tags | Create, list, rename, delete tags; tag/untag notes | | joplin-manage-resources | Upload, download, list, and delete file attachments |

Option B: MCP Server

Install

cd mcp
npm install
npm run build

Register with Claude Code

claude mcp add joplin -- node /absolute/path/to/joplin-skills/mcp/build/index.js

Make sure JOPLIN_TOKEN is set in your environment before starting Claude Code, or configure it in .claude/settings.local.json.

MCP Tools

The server exposes these tools: joplin_get_note, joplin_list_notes, joplin_create_note, joplin_update_note, joplin_delete_note, joplin_search, joplin_list_notebooks, joplin_create_notebook, joplin_update_notebook, joplin_delete_notebook, joplin_get_notebook_notes, joplin_list_tags, joplin_create_tag, joplin_tag_note, joplin_untag_note, joplin_list_resources.

Project Structure

joplin-skills/
├── README.md
├── .gitignore
├── skills/                          # Skill definitions (browse on GitHub)
│   ├── joplin/
│   │   ├── SKILL.md                 # Main skill — routing & direct operations
│   │   └── api-reference.md         # Full Joplin REST API reference
│   ├── joplin-create-note/
│   │   └── SKILL.md
│   ├── joplin-search/
│   │   └── SKILL.md
│   ├── joplin-manage-notebooks/
│   │   └── SKILL.md
│   ├── joplin-manage-tags/
│   │   └── SKILL.md
│   └── joplin-manage-resources/
│       └── SKILL.md
├── mcp/                             # MCP server (TypeScript)
│   ├── src/index.ts
│   ├── package.json
│   └── tsconfig.json
└── .claude/
    └── skills/                      # Same as skills/ — used by Claude Code at runtime

License

MIT

MCP Servers