Skip to main content
Glama
Joplin Server MCP

Joplin Server MCP

README.md
# Joplin Server MCP

[Model Context Protocol](https://modelcontextprotocol.io/) server for [Joplin Server](https://github.com/laurent22/joplin/tree/dev/packages/server). Gives LLMs full access to your notes, notebooks, tags, and attachments via the Joplin Server REST API.

## What is Joplin Server?

[Joplin](https://joplinapp.org/) is an open-source note-taking app with Markdown support, end-to-end encryption, and sync across devices. [Joplin Server](https://github.com/laurent22/joplin/tree/dev/packages/server) is the sync backend that stores and syncs your data. You can run it yourself using the official [Docker image](https://hub.docker.com/r/joplin/server) or use the managed [Joplin Cloud](https://joplincloud.com/) service.

> **Note:** This MCP server connects to **Joplin Server** REST API, not the Joplin Desktop Web Clipper.
>
> **Joplin Cloud:** Use `JOPLIN_SERVER_URL=https://api.joplincloud.com`.

## Tools

| Tool | Description |
|---|---|
| `ping_joplin` | Check server connectivity |
| `list_notebooks` | List all notebooks |
| `get_notebook` | Get notebook details with notes and sub-notebooks |
| `create_notebook` | Create a new notebook |
| `get_or_create_notebook` | Resolve a `/`-separated notebook path, creating missing levels |
| `update_notebook` | Rename or move a notebook (with circular reference check) |
| `delete_notebook` | Delete a notebook (with optional force for non-empty) |
| `list_notes` | List notes, optionally filtered by notebook, tag, and/or to-do state |
| `get_all_notes` | Get all notes with pagination, sorting (incl. `todo_due`/`todo_completed`), notebook and to-do filters |
| `search_notes` | Search notes (multi-term AND) with scope and notebook/tag filters |
| `get_note` | Get note text (resource references replaced with names, or `raw=True` for the verbatim body) |
| `get_notes_batch` | Read multiple notes at once (up to 50, parallel) |
| `get_note_full` | Get note with all resources embedded as base64 |
| `create_note` | Create a new note (optionally as a to-do with a due date) |
| `export_note` | Export note as markdown with resources as named base64 blocks |
| `update_note` | Update note title, body, or move to another notebook |
| `get_note_outline` | Map a note's headings with line numbers and section sizes |
| `append_to_note` | Add text inside a note or section, or as a sibling before/after a section |
| `replace_in_note` | Replace an exact string inside a note body |
| `replace_section` | Replace everything under a heading |
| `set_todo` | Set/clear a note's to-do state, completion, and due date |
| `delete_note` | Delete a note |
| `list_tags` | List all tags |
| `create_tag` | Create a new tag |
| `delete_tag` | Delete a tag |
| `get_note_tags` | List tags assigned to a note |
| `add_tag_to_note` | Add a tag to a note |
| `remove_tag_from_note` | Remove a tag from a note |
| `get_note_resources` | List resources attached to a note |
| `get_resource_info` | Get resource metadata |
| `download_resource` | Download a resource as base64 |

## Partial edits

`update_note` takes the complete new body, which makes it a poor fit for large
notes: adding two lines to a 70 KB note means an LLM has to reproduce all 70 KB
verbatim. That is expensive, and a single silent typo corrupts the note.

`append_to_note`, `replace_in_note` and `replace_section` resolve the edit on
the server instead. The client sends only the fragment it wants added or
changed, so untouched text — including `:/<resource-id>` links, which the read
tools render as human-readable names — is preserved byte for byte.

```
append_to_note(note_id, "| web-1 | 10.0.0.5 |", section="Hosts", separator="\n")
append_to_note(note_id, "## 2026-08-26\n\nDeployed.", section="## 2026-08-25", position="before")
replace_in_note(note_id, "status: draft", "status: final")
replace_section(note_id, "## Current state", "Rewritten from scratch.")
```

Every write reports what it did — character and line deltas, heading count
before and after, and the numbered lines around the change — so the result can
be verified without re-reading the note:

```
Appended to: **Work Log** (ID: `0123456789abcdef0123456789abcdef`)
Inserted 745 chars at the start of section '# Work Log' (line 1)
Chars 76141 -> 76887 (+746), lines 1858 -> 1885 (+27), headings 117 -> 118
```

Guard rails:

- **Sections are addressed by heading**, either bare (`"Hosts"`) or with its
  level (`"## Hosts"`), and a section ends at the next heading of the same or
  higher level. Headings inside fenced code blocks are ignored. An ambiguous or
  missing heading is refused, never guessed. `get_note_outline` lists what is
  available without reading the body.
- **`position` picks inside or beside.** `"start"` / `"end"` write inside the
  note or section, joining the existing content with `separator`. `"before"` /
  `"after"` place the text beside a named section instead — above its heading,
  or past its whole span with subsections included. Those two require
  `section`, ignore `separator`, and are strictly additive: no existing byte is
  rewritten and blank lines appear only where the join needs them. Reach for
  `"before"` to put a new entry at the top of a newest-first log whose first
  heading is preceded by a preamble — `"start"` would land above the preamble.
- **`replace_in_note` demands a unique match.** A missing anchor or an
  unexpected second match is an error, with the mismatching lines reported.
  Use `get_note(raw=True)` to copy an anchor verbatim, or `replace_all=True`
  when you do mean every occurrence.
- **`dry_run=True`** reports the change and its context without writing.
- **`if_absent="marker"`** skips the append when the marker is already in the
  note, which makes a re-run a no-op.

## Setup

### Prerequisites

- A running [Joplin Server](https://github.com/laurent22/joplin/tree/dev/packages/server) instance or [Joplin Cloud](https://joplincloud.com/) account
- User credentials (email + password)

### Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `JOPLIN_SERVER_URL` | Yes | — | Joplin Server URL |
| `JOPLIN_EMAIL` | Yes (single-user) | — | User email |
| `JOPLIN_PASSWORD` | Yes (single-user) | — | User password |
| `MCP_TRANSPORT` | No | `stdio` (`sse` in the Docker image) | Transport: `stdio`, `sse` or `streamable-http` |
| `MCP_HOST` | No | `0.0.0.0` | HTTP listen host (`sse` and `streamable-http`) |
| `MCP_PORT` | No | `8081` | HTTP listen port (`sse` and `streamable-http`) |
| `JOPLIN_MULTI_USER` | No | `0` | `1` = take each user's credentials from a request header, see [Multi-user mode](#multi-user-mode) |
| `JOPLIN_CREDENTIALS_HEADER` | No | `X-Joplin-Credentials` | Multi-user: name of the header carrying `email:password` |
| `JOPLIN_ACCOUNT_IDLE_MINUTES` | No | `30` | Multi-user: evict an account (index, session, password) after this much idle time |
| `JOPLIN_DISK_CACHE` | No | `1` | `0` disables the on-disk index cache |
| `JOPLIN_CACHE_DIR` | No | `/tmp/joplin-cache` | Multi-user: directory of the per-account cache files |

`streamable-http` serves the endpoint `/mcp` and is the transport the current
MCP specification recommends; `sse` (endpoint `/sse`) is the older one, kept as
the image default for compatibility.

### Run with Docker

```bash
docker run -d \
  -e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
  -e JOPLIN_EMAIL=your@email.com \
  -e JOPLIN_PASSWORD=your_password \
  -p 8081:8081 \
  alexfail2/joplin-mcp
```

The container defaults to SSE transport. The endpoint will be available at `http://localhost:8081/sse`.
Add `-e MCP_TRANSPORT=streamable-http` to serve `http://localhost:8081/mcp` instead.

### Run locally (stdio)

```bash
pip install -r requirements.txt   # mcp, httpx, uvicorn, pinned
python app/server.py
```

### Build from source

```bash
docker build -t joplin-mcp .
```

## MCP client configuration

### Streamable HTTP

```json
{
  "mcpServers": {
    "joplin": {
      "url": "http://localhost:8081/mcp"
    }
  }
}
```

### SSE (Docker default)

```json
{
  "mcpServers": {
    "joplin": {
      "url": "http://localhost:8081/sse"
    }
  }
}
```

### stdio (local)

```json
{
  "mcpServers": {
    "joplin": {
      "command": "python",
      "args": ["/path/to/app/server.py"],
      "env": {
        "JOPLIN_SERVER_URL": "https://your-joplin-server.example.com",
        "JOPLIN_EMAIL": "your@email.com",
        "JOPLIN_PASSWORD": "your_password"
      }
    }
  }
}
```

## Multi-user mode

By default one server instance serves one Joplin account (the one in
`JOPLIN_EMAIL` / `JOPLIN_PASSWORD`). With `JOPLIN_MULTI_USER=1` a single
instance serves many users: each request carries that user's own Joplin
credentials in a header, and every tool call runs against that user's account.

### How it works

- The client sends `X-Joplin-Credentials: email:password` with every request
  (the value is split at the **first** colon, so passwords may contain colons).
  The header name is configurable with `JOPLIN_CREDENTIALS_HEADER`.
- An ASGI middleware reads the header, logs in to Joplin Server (or reuses the
  session it already has for that account) and binds the account to the request.
  Without the header, or with credentials Joplin rejects, the request is
  answered with **HTTP 401** before reaching any tool, so clients report
  "unauthorized" instead of a tool error. More than 5 failed logins for one
  account within 5 minutes are answered with **429**.
- Each account has its own state: session, index, resource index and background
  refresh tasks. Accounts are keyed by `sha256(server URL + lowercased email)`;
  an account idle for `JOPLIN_ACCOUNT_IDLE_MINUTES` (default 30) is evicted and
  its background tasks cancelled.
- `JOPLIN_SERVER_URL` is only read from the environment, never from a header.
  `JOPLIN_EMAIL` / `JOPLIN_PASSWORD` are not required and are never used in
  this mode.
- The index cache on disk is one file per account in `JOPLIN_CACHE_DIR`, named
  by the account hash, mode `0600` in a `0700` directory, and loaded only after
  a successful login. `JOPLIN_DISK_CACHE=0` turns it off. The files contain note
  titles and bodies in clear, so put the directory on storage you trust.
- Credentials are never logged or put in error messages.
- Multi-user mode needs an HTTP transport. `streamable-http` is recommended: it
  runs stateless, so each request is executed with the credentials of that
  request. With `sse` the account is fixed when the SSE connection is opened.
- Single-user mode is unchanged: no header is needed, stdio works, and if a
  credentials header is sent anyway it is ignored (a warning is logged once).

### Docker example

```bash
docker run -d \
  -e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
  -e JOPLIN_MULTI_USER=1 \
  -e MCP_TRANSPORT=streamable-http \
  -v joplin-mcp-cache:/tmp/joplin-cache \
  -p 127.0.0.1:8081:8081 \
  alexfail2/joplin-mcp
```

### Client configuration

Any MCP client that can send a per-user header works, for example a chat
application whose connector lets each user provide their own key and choose the
header name:

```json
{
  "mcpServers": {
    "joplin": {
      "url": "https://joplin-mcp.internal.example.com/mcp",
      "headers": { "X-Joplin-Credentials": "you@example.com:your_joplin_password" }
    }
  }
}
```

### Limitations

- Joplin Server has no personal access tokens. Each user's Joplin **password**
  is therefore sent with every request, and the client has to store it
  (encrypted in the client, if it supports that).
- The MCP server holds the password of every active user in memory and logs in
  to Joplin on their behalf. **A compromise of the server exposes the accounts
  of all active users.** Run it only on a private network or behind TLS, never
  on the public internet without TLS.
- One Joplin Server per instance (`JOPLIN_SERVER_URL`).
- The index is kept per user in memory, so memory grows with the number of
  active users; idle accounts are evicted after `JOPLIN_ACCOUNT_IDLE_MINUTES`.
- There is no revocation separate from Joplin itself: changing the Joplin
  password is the only way to cut access (an already-open session keeps working
  until Joplin rejects it).

## How it works

The server authenticates with Joplin Server via email/password sessions and builds an in-memory index of all items (notes, notebooks, tags) with a 2-minute TTL cache. Incremental sync compares server-side `updated_time` with cached etags, fetching only changed items (typical refresh: ~5s vs ~35s full rebuild). The index is persisted to `/tmp/joplin_index_cache.json` (one file per account in multi-user mode, see above; `JOPLIN_DISK_CACHE=0` disables it) so a restarted container starts instantly; a recreated one rebuilds it on first use. Resource metadata is loaded lazily on first access. Background refresh keeps the index up to date without blocking requests. All IDs are validated (32-char hex) before API calls.

Joplin's internal serialization format (title + markdown body + metadata block) is parsed and presented as clean structured output.

## Development

The pure helpers (markdown section resolution, splicing, edit reports, to-do
state) are covered by a dependency-free test suite:

```bash
python tests/test_helpers.py
```

The multi-user tests use `pytest` and a fake Joplin API (`tests/fake_joplin.py`):

```bash
pip install -r requirements-dev.txt
python -m pytest tests
python tests/smoke_multi_user.py 8381   # end-to-end, streamable-http, two users
```

## Contributors

- [@paoloviviani](https://github.com/paoloviviani) — to-do state: completion and
  due dates surfaced and settable, `set_todo`, `create_note` flags, `todo`
  filters and ordering ([#7](https://github.com/Alexander-Zhukov/joplin-server-mcp/pull/7))
- [@LasseLegarth](https://github.com/LasseLegarth) — `share_id` inherited from
  the parent notebook, so notes stay visible to a shared notebook's participants
  ([#5](https://github.com/Alexander-Zhukov/joplin-server-mcp/pull/5))


## License

[MIT](LICENSE)