convez.ai
MCP ServerIntegração & APIsIntermediário
wickes1

Joplin MCP Server

wickes1/joplin-mcp

Controle total do Joplin via assistentes de IA com 27 ferramentas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
v0.3.0
Issues abertas
0
Contribuidores
1

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

VariableDefaultDescription
JOPLIN_TOKEN(required)Joplin Web Clipper API token
JOPLIN_HOSTlocalhostJoplin API host
JOPLIN_PORT41184Joplin API port
JOPLIN_LOG_LEVELinfoLog level: debug, info, warn, error
JOPLIN_READ_TIMEOUT30Per-request timeout in seconds for GET operations
JOPLIN_WRITE_TIMEOUT120Per-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)

ToolDescription
list_notesList notes, optionally filtered by folder. Returns slim notes and a has_more flag.
get_noteGet a single note by ID with full body and tags.
get_notesBatch-read up to 50 notes by ID. Failed lookups are included as error entries.
create_noteCreate a new note. Optionally auto-create folder by name and apply tags.
update_noteUpdate an existing note's title, body, folder, or to-do status. folder_name auto-creates if not found.
delete_noteDelete a note by ID. By default moves to trash; set permanent=true to bypass trash.

Search (1 tool)

ToolDescription
search_notesFull-text search across all notes. Returns preview notes (200-char body preview) and a has_more flag.

Folders (4 tools)

ToolDescription
list_foldersList all folders as a nested tree with computed paths (e.g. Work/Projects/Q1).
create_folderCreate a new folder, optionally nested under a parent folder.
update_folderRename or move a folder.
delete_folderDelete a folder by ID. By default moves to trash; set permanent=true to bypass trash.

Tags (5 tools)

ToolDescription
list_tagsList all tags in the Joplin library.
tag_noteApply a tag to a note. Creates the tag if it does not exist (case-insensitive).
untag_noteRemove a tag from a note (case-insensitive tag lookup).
delete_tagDelete a tag by ID. Removes it from all notes.
get_notes_by_tagGet notes associated with a tag name (case-insensitive). Returns slim notes and a has_more flag.

Batch (3 tools)

ToolDescription
batch_move_notesMove up to 100 notes to a destination folder concurrently.
batch_tag_notesAdd or remove a tag from up to 100 notes concurrently. Creates the tag automatically when adding.
merge_notesFetch up to 50 notes, concatenate their bodies with headings and separators, create a new merged note.

Export / Import (2 tools)

ToolDescription
export_notesExport Joplin notes to the filesystem as Markdown files, preserving folder hierarchy with optional YAML frontmatter.
batch_import_markdownWalk a directory for .md files and import each as a Joplin note, optionally preserving directory structure as folders.

Resources (4 tools)

ToolDescription
list_resourcesList Joplin resources (attachments). Returns a page of resources and a has_more flag.
get_resourceGet metadata for a single Joplin resource (attachment) by ID.
download_resourceDownload a Joplin resource (attachment) file to a local path on disk.
upload_resourceUpload a local file as a Joplin resource. Returns an ID for embedding: ![alt](:/id) or [name](:/id).

Utility (2 tools)

ToolDescription
import_markdownImport a single Markdown (.md) file into Joplin as a note. Title extracted from the first # heading or filename.
get_statusCheck 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

Ver o original no GitHub

Bom para

Relacionados