joplin-plugin-mcp/README.md

# Joplin MCP Server

A [Joplin](https://joplinapp.org/) plugin that exposes your notes as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server. This allows AI assistants such as **Claude Desktop**, **Cursor**, **VS Code Copilot**, **Kilo**, and any other MCP-compatible client to create, read, update, and delete notes, notebooks, and tags, as well as search through your Joplin vault — directly through the standard MCP protocol.

## Features

- **Full note management** — create, read, update, and delete notes (including to-dos)
- **Notebook operations** — list, create, rename, move, and delete notebooks with tree view
- **Tag management** — create, rename, delete tags; add/remove tags from notes
- **Powerful search** — search notes, notebooks, and tags using Joplin's built-in search engine with advanced query syntax
- **20 MCP tools** covering all common note-taking operations
- **Streamable HTTP transport** — no stdio or local process required; works over HTTP
- **Session management** with automatic stale-session cleanup (30-minute TTL)
- **Configurable** — custom host and port settings within Joplin
- **CORS support** — works with browser-based clients and IDE extensions

## Requirements

- **Joplin** >= 3.5
- An MCP-compatible client (Claude Desktop, Cursor, VS Code Copilot, Kilo, etc.)

## Installation

### From the Joplin Plugin Directory

1. Open Joplin
2. Go to **Tools** > **Options** > **Plugins**
3. Search for **"MCP Server"**
4. Click **Install**
5. Restart Joplin when prompted

### Manually from Release

1. Download the latest `net.hunnius.mcpserver.jpl` file from the [releases page](https://codeberg.org/jhunnius/joplin-plugin-mcp/releases)
2. Open Joplin
3. Go to **Tools** > **Options** > **Plugins**
4. Click the gear icon and select **Install from file**
5. Select the downloaded `.jpl` file
6. Restart Joplin when prompted

## Configuration

After installation, the MCP server starts automatically when Joplin launches. By default it listens on `http://127.0.0.1:22123/mcp`.

To change the host or port:

1. Open Joplin
2. Go to **Tools** > **Options** > **MCP Server**
3. Adjust the **Port** (default: `22123`, range: 1024–65535)
4. Adjust the **Host** (default: `127.0.0.1`)

> **Note:** You must restart Joplin for changes to take effect.

## MCP Client Setup

Configure your AI assistant to connect to the Joplin MCP server. The endpoint is:

```
http://127.0.0.1:22123/mcp
```

### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp"
    }
  }
}
```

### Claude Desktop / VS Code Copilot

Add to your `mcp.json` configuration file:

```json
{
  "servers": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp",
      "type": "streamableHttp"
    }
  }
}
```

### Kilo

Add to your `kilo.json`:

```json
{
  "mcps": {
    "joplin": {
      "url": "http://127.0.0.1:22123/mcp",
      "type": "streamableHttp"
    }
  }
}
```

### Generic MCP Client

Any client supporting the Streamable HTTP transport can connect to `http://127.0.0.1:22123/mcp`. The server implements the standard MCP protocol with session management via the `mcp-session-id` header.

## Available Tools

The plugin provides 20 MCP tools:

### Notes

| Tool | Description |
|---|---|
| `create_note` | Create a new note with optional title, body, notebook, to-do status, due date, and tags |
| `get_note` | Retrieve a specific note by ID, including full body, metadata, and tags |
| `update_note` | Update an existing note's title, body, notebook, to-do status, due date, or source URL |
| `delete_note` | Soft-delete a note (moved to trash) |
| `list_notes` | List notes with pagination, optional notebook filter, and sort options |
| `get_notes_by_ids` | Retrieve multiple notes by their IDs in a single call |

### Notebooks

| Tool | Description |
|---|---|
| `list_notebooks` | List all notebooks as a tree hierarchy |
| `get_notebook` | Get notebook details including sub-notebooks and contained notes |
| `create_notebook` | Create a new notebook, optionally nested under a parent |
| `update_notebook` | Rename a notebook or move it to a different parent |
| `delete_notebook` | Soft-delete a notebook and all its notes |

### Tags

| Tool | Description |
|---|---|
| `list_tags` | List all tags |
| `create_tag` | Create a new tag (returns existing if duplicate) |
| `update_tag` | Rename an existing tag |
| `delete_tag` | Permanently delete a tag (removed from all notes) |
| `get_note_tags` | List all tags assigned to a specific note |
| `add_tag_to_note` | Add a tag to a note (auto-creates the tag if it doesn't exist) |
| `remove_tag_from_note` | Remove a tag from a note |

### Search

| Tool | Description |
|---|---|
| `search_notes` | Search notes using Joplin's query syntax (`title:`, `body:`, `tag:`, `notebook:`, `-exclude`, `OR`, etc.) |
| `search_notebooks` | Search notebooks by title |
| `search_tags` | Search tags by title |
| `search_all` | Search across notes, notebooks, and tags simultaneously |

### Utility

| Tool | Description |
|---|---|
| `ping` | Test connectivity to the MCP server (returns `pong`) |

## Search Syntax

Joplin's search engine supports advanced queries:

| Syntax | Description |
|---|---|
| `word` | Search for notes containing "word" |
| `*` | List all items |
| `title:word` | Search in note titles |
| `body:word` | Search in note bodies |
| `tag:name` | Search by tag |
| `notebook:name` | Search within a notebook |
| `created:20240101` | Filter by creation date |
| `updated:20240101` | Filter by update date |
| `any:word1 word2` | Match any of the words |
| `-word` | Exclude notes containing "word" |
| `word1 OR word2` | Match either word |

## Security Considerations

- **Localhost by default** — the server binds to `127.0.0.1`, making it accessible only from the local machine
- **CORS protection** — only requests from `localhost`, `127.0.0.1`, and `vscode-webview://` origins are accepted from browsers; non-browser clients (like CLI tools) are allowed by default
- **No authentication** — the server does not require an API token or password. This is intentional for local-use simplicity. If you bind to `0.0.0.0`, anyone on your network can access your Joplin data
- **Network exposure** — binding to `0.0.0.0` is supported for advanced use cases but should only be used on trusted, isolated networks

## Development

### Prerequisites

- Node.js >= 16
- npm

### Build from Source

```bash
git clone https://codeberg.org/jhunnius/joplin-plugin-mcp.git
cd joplin-plugin-mcp
npm install
npm run dist
```

The built plugin is output to `publish/net.hunnius.mcpserver.jpl`.

### Install Development Build

1. Build the plugin as described above
2. In Joplin, go to **Tools** > **Options** > **Plugins**
3. Click the gear icon and select **Install from file**
4. Select `publish/net.hunnius.mcpserver.jpl`

### Project Structure

```
src/
├── index.ts    # Plugin entry point, settings registration
├── server.ts   # HTTP server, session management, CORS
└── tools.ts    # MCP tool definitions and handlers
```

## License

[MIT](https://codeberg.org/jhunnius/joplin-plugin-mcp/src/branch/master/LICENSE) © Jan-Peter v. Hunnius

## Links

- **Repository:** <https://codeberg.org/jhunnius/joplin-plugin-mcp>
- **Issues:** <https://codeberg.org/jhunnius/joplin-plugin-mcp/issues>
- **Joplin:** <https://joplinapp.org/>
- **MCP Specification:** <https://modelcontextprotocol.io/>