jan/joplin-plugin-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: implement MCP server plugin v1.0.0

Browse source 
Add HTTP-based MCP server exposing 20 Joplin tools (notes, notebooks,
tags, search) via StreamableHTTPServerTransport. Includes configurable
host/port settings, CORS support, and session management.

- src/index.ts: Plugin registration and settings UI
- src/server.ts: MCP HTTP server with StreamableHTTP transport
- src/tools.ts: 20 MCP tool definitions for Joplin operations
- LICENSE: MIT license
- CHANGELOG.md: v1.0.0 changelog entry
- README.md: Comprehensive documentation
This commit is contained in:
Jan-Peter von Hunnius 2026-05-31 12:57:22 +02:00
parent de18d28146
commit 65ec128efe
12 changed files with 1358 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

231
README.md
View file

@ -1,5 +1,230 @@
# Joplin Plugin
# Joplin MCP Server
This is your new Joplin plugin. It is suggested that you use this README file to document your plugin.
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.
For information on how to build or publish the plugin, please see [GENERATOR_DOC.md](./GENERATOR_DOC.md)
## 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/>