# joplin-connect

Claude Code skills and MCP server for managing [Joplin](https://joplinapp.org/) 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

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

## Setup

### Set your Joplin API token

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

```bash
export JOPLIN_TOKEN="your_api_token_here"
```

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

```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:

```bash
# 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

```bash
cd mcp
npm install
npm run build
```

### Register with Claude Code

```bash
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