Joplin MCP Server
wickes1/joplin-mcp
Controle total do Joplin via assistentes de IA com 27 ferramentas
Ver no GitHubServidor MCP em Go que conecta assistentes de IA ao Joplin Desktop para gerenciamento completo de notas. Oferece 27 ferramentas cobrindo notas, pastas, tags, busca, operações em lote, importação/exportação e gerenciamento de recursos, integrando-se perfeitamente com Claude e outros assistentes compatíveis.
Instalação
npx convez-ai wickes1/joplin-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar criação, atualização e organização de notas via IA
- Buscar e recuperar informações de notas por comando de linguagem natural
- Mover, etiquetar e mesclar notas em lote através de assistentes
- Importar/exportar notas em Markdown de forma automatizada
- Gerenciar anexos e recursos de notas remotamente
Veredito

Implementação sólida de MCP server que expõe toda a API do Joplin de forma estruturada. Excelente para quem já usa Joplin e quer automação avançada via Claude; exige configuração de token e Joplin Desktop rodando localmente.
README
A tradução para o português deste README ainda está na fila.
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 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
brew tap wickes1/tap
brew install joplin-mcp
Go
go install github.com/Wickes1/joplin-mcp@latest
Binary
Download pre-built binaries from GitHub 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):
{
"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_TOKENto 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, andtags[]. 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_notecall.
Write operations (create_note, update_note, etc.) return slim responses; read operations (get_note, get_notes) return full responses.
License
MIT