# Joplin Mcp

> A Go MCP server that connects AI assistants to Joplin desktop for complete note management

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

## Install

```sh
agentstack add mcp-wickes1-joplin-mcp
```

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

## About

# joplin-mcp

A Go-based MCP server that connects AI assistants to Joplin desktop for complete note management.

## Features

27 tools covering notes, folders, tags, search, batch operations, export/import, and resource management — all accessible to any MCP-compatible AI assistant (Claude, etc.).

- **Notes**: create, read, update, delete, batch-read
- **Search**: full-text search with body previews
- **Folders**: list, create, rename, delete (nested tree with computed paths)
- **Tags**: list, apply, remove, delete, query notes by tag
- **Batch**: move notes, tag/untag in bulk, merge notes
- **Export/Import**: export to Markdown files, bulk import from directory
- **Resources**: list, inspect, download, and upload attachments
- **Utility**: connectivity check, import single Markdown file

## Prerequisites

- [Joplin desktop](https://joplinapp.org/) installed and running
- Web Clipper enabled: **Settings → Web Clipper → Enable Web Clipper Service**
- Copy your API token from the Web Clipper settings page

## Installation

### Homebrew

```bash
brew tap wickes1/tap
brew install joplin-mcp
```

### Go

```bash
go install github.com/Wickes1/joplin-mcp@latest
```

### Binary

Download pre-built binaries from [GitHub Releases](https://github.com/wickes1/joplin-mcp/releases).

Available for: macOS (Intel/Apple Silicon), Linux (x86_64/arm64), Windows (x86_64/arm64).

## Configuration

Add to your `.mcp.json` (or Claude Code's MCP config):

```json
{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp",
      "env": {
        "JOPLIN_TOKEN": "your-token-here",
        "JOPLIN_HOST": "localhost",
        "JOPLIN_PORT": "41184"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `JOPLIN_TOKEN` | (required) | Joplin Web Clipper API token |
| `JOPLIN_HOST` | `localhost` | Joplin API host |
| `JOPLIN_PORT` | `41184` | Joplin API port |
| `JOPLIN_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `JOPLIN_READ_TIMEOUT` | `30` | Per-request timeout in seconds for GET operations |
| `JOPLIN_WRITE_TIMEOUT` | `120` | Per-request timeout in seconds for POST/PUT/DELETE operations |

> **Security**: Do not commit `JOPLIN_TOKEN` to version control. On macOS, store it in Keychain and inject it via a wrapper script.

## Tools Reference

### Notes (6 tools)

| Tool | Description |
|------|-------------|
| `list_notes` | List notes, optionally filtered by folder. Returns slim notes and a `has_more` flag. |
| `get_note` | Get a single note by ID with full body and tags. |
| `get_notes` | Batch-read up to 50 notes by ID. Failed lookups are included as error entries. |
| `create_note` | Create a new note. Optionally auto-create folder by name and apply tags. |
| `update_note` | Update an existing note's title, body, folder, or to-do status. `folder_name` auto-creates if not found. |
| `delete_note` | Delete a note by ID. By default moves to trash; set `permanent=true` to bypass trash. |

### Search (1 tool)

| Tool | Description |
|------|-------------|
| `search_notes` | Full-text search across all notes. Returns preview notes (200-char body preview) and a `has_more` flag. |

### Folders (4 tools)

| Tool | Description |
|------|-------------|
| `list_folders` | List all folders as a nested tree with computed paths (e.g. `Work/Projects/Q1`). |
| `create_folder` | Create a new folder, optionally nested under a parent folder. |
| `update_folder` | Rename or move a folder. |
| `delete_folder` | Delete a folder by ID. By default moves to trash; set `permanent=true` to bypass trash. |

### Tags (5 tools)

| Tool | Description |
|------|-------------|
| `list_tags` | List all tags in the Joplin library. |
| `tag_note` | Apply a tag to a note. Creates the tag if it does not exist (case-insensitive). |
| `untag_note` | Remove a tag from a note (case-insensitive tag lookup). |
| `delete_tag` | Delete a tag by ID. Removes it from all notes. |
| `get_notes_by_tag` | Get notes associated with a tag name (case-insensitive). Returns slim notes and a `has_more` flag. |

### Batch (3 tools)

| Tool | Description |
|------|-------------|
| `batch_move_notes` | Move up to 100 notes to a destination folder concurrently. |
| `batch_tag_notes` | Add or remove a tag from up to 100 notes concurrently. Creates the tag automatically when adding. |
| `merge_notes` | Fetch up to 50 notes, concatenate their bodies with headings and separators, create a new merged note. |

### Export / Import (2 tools)

| Tool | Description |
|------|-------------|
| `export_notes` | Export Joplin notes to the filesystem as Markdown files, preserving folder hierarchy with optional YAML frontmatter. |
| `batch_import_markdown` | Walk a directory for `.md` files and import each as a Joplin note, optionally preserving directory structure as folders. |

### Resources (4 tools)

| Tool | Description |
|------|-------------|
| `list_resources` | List Joplin resources (attachments). Returns a page of resources and a `has_more` flag. |
| `get_resource` | Get metadata for a single Joplin resource (attachment) by ID. |
| `download_resource` | Download a Joplin resource (attachment) file to a local path on disk. |
| `upload_resource` | Upload a local file as a Joplin resource. Returns an ID for embedding: `` or `[name](:/id)`. |

### Utility (2 tools)

| Tool | Description |
|------|-------------|
| `import_markdown` | Import a single Markdown (`.md`) file into Joplin as a note. Title extracted from the first `#` heading or filename. |
| `get_status` | Check Joplin connectivity and return library statistics (folder count, tag count, port). |

## Response Design

Tools follow a **slim / full / preview** pattern to keep token usage low:

- **Slim** (list operations): `id`, `title`, `parent_id`, `folder_title`, `is_todo`, `updated_time`. Used for browsing without fetching note bodies.
- **Full** (get_note, get_notes): All slim fields plus `body`, `created_time`, `todo_completed`, and `tags[]`. Used when content is needed.
- **Preview** (search): Slim fields plus the first 200 characters of the body. Usually enough to judge relevance without a follow-up `get_note` call.

Write operations (`create_note`, `update_note`, etc.) return slim responses; read operations (`get_note`, `get_notes`) return full responses.

## License

MIT

## Source & license

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

- **Author:** [wickes1](https://github.com/wickes1)
- **Source:** [wickes1/joplin-mcp](https://github.com/wickes1/joplin-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:** no
- **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-wickes1-joplin-mcp
- Seller: https://agentstack.voostack.com/s/wickes1
- 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%.