# Joplin Server Mcp

> Simple mcp for joplin server

- **Type:** MCP server
- **Install:** `agentstack add mcp-alexander-zhukov-joplin-server-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Alexander-Zhukov](https://agentstack.voostack.com/s/alexander-zhukov)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Alexander-Zhukov](https://github.com/Alexander-Zhukov)
- **Source:** https://github.com/Alexander-Zhukov/joplin-server-mcp

## Install

```sh
agentstack add mcp-alexander-zhukov-joplin-server-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 and/or tag |
| `get_all_notes` | Get all notes with pagination, sorting, and notebook filter |
| `search_notes` | Search notes (multi-term AND) with scope and notebook/tag filters |
| `get_note` | Get note text (resource references replaced with names) |
| `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 |
| `export_note` | Export note as markdown with resources as named base64 blocks |
| `update_note` | Update note title, body, or move to another notebook |
| `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 |

## 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 | — | User email |
| `JOPLIN_PASSWORD` | Yes | — | User password |
| `MCP_TRANSPORT` | No | `stdio` | Transport: `stdio` or `sse` |
| `MCP_HOST` | No | `0.0.0.0` | SSE listen host |
| `MCP_PORT` | No | `8081` | SSE listen port |

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

### Run locally (stdio)

```bash
pip install mcp httpx
python app/server.py
```

### Build from source

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

## MCP client configuration

### SSE (Docker)

```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"
      }
    }
  }
}
```

## 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 disk so container restarts are instant. 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.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Alexander-Zhukov](https://github.com/Alexander-Zhukov)
- **Source:** [Alexander-Zhukov/joplin-server-mcp](https://github.com/Alexander-Zhukov/joplin-server-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-alexander-zhukov-joplin-server-mcp
- Seller: https://agentstack.voostack.com/s/alexander-zhukov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.