Joplin MCP Server
gelse/joplin-mcp
Acesso a notas Joplin via Model Context Protocol para assistentes de IA
Ver no GitHubServidor MCP que expõe a funcionalidade de anotações do Joplin — notas, pastas, tags, busca e sincronização — para assistentes de IA. Integra o Joplin desktop ou servidor com Claude via 16 ferramentas especializadas.
Instalação
npx convez-ai gelse/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
- Integrar gerenciamento de notas Joplin em workflows com Claude
- Automatizar criação, busca e sincronização de notas via IA
- Construir assistentes que consultam base de conhecimento em Joplin
Veredito

Implementação técnica sólida de um servidor MCP TypeScript para Joplin com suporte a Data API local e Joplin Server remoto. Excelente para quem já usa Joplin e quer integrar assistentes de IA, mas requer configuração de ambiente e conhecimento de MCP.
README
A tradução para o português deste README ainda está na fila.
Joplin API MCP Server
An MCP (Model Context Protocol) server that exposes Joplin's note-taking functionality — notes, folders, tags, search, and sync — to AI assistants via 16 tools.
tl;dr / Quick Start
Direct Installation
Prerequisites: Node.js 20+, pnpm 9+, a running Joplin desktop app with the Data API enabled (Web Clipper → Options → Enable Clipper Server), and optionally Joplin Server for sync.
git clone <repo-url> && cd joplin-api
cp .env.example .env # fill in JOPLIN_SERVER_URL, JOPLIN_USERNAME, JOPLIN_PASSWORD
pnpm install
pnpm build && pnpm start
Add this to your MCP client config (Claude Desktop, VS Code, etc.):
{
"mcpServers": {
"joplin": {
"command": "node",
"args": ["/path/to/joplin-api/dist/server.js"],
"env": {
"JOPLIN_SERVER_URL": "https://joplin.example.com/",
"JOPLIN_USERNAME": "your-email@example.com",
"JOPLIN_PASSWORD": "your-password"
}
}
}
}
See MCP Client Configuration below for Docker-based and other client setups.
Docker
cp .env.example .env # fill in required variables
docker compose up -d # or `docker-compose up -d`
The .env file is automatically picked up by docker-compose.yml. The server starts in the background and listens on stdio for MCP requests.
Detailed How-To
Direct Installation
Prerequisites
- Node.js 20 or later (the project's
package.jsonenginesfield requires>=22.0.0) - pnpm 9 or later (for package management)
- Joplin desktop app running with the Data API (ClipperServer) enabled:
- In Joplin: Web Clipper → Options → Enable Clipper Server
- The server binds to
127.0.0.1:41184by default and ignores--host/--portflags
- Joplin Server (optional but recommended) — a sync target for multi-device synchronisation. Without it, write-through sync will fail and notes remain local-only
Installation
git clone <repo-url>
cd joplin-api
pnpm install
pnpm build
Configuration
Copy the environment template and fill in your values:
cp .env.example .env
All configuration is done via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
JOPLIN_SERVER_URL | Yes | — | Joplin Server URL (e.g., https://joplin.example.com/) |
JOPLIN_USERNAME | Yes | — | Joplin Server username/email |
JOPLIN_PASSWORD | Yes | — | Joplin Server password |
JOPLIN_DATA_API_PORT | No | 41184 | Internal Data API listen port (Joplin ClipperServer hardcoded default) |
LOG_LEVEL | No | info | Log level: debug, info, warn, error, silent |
SYNC_INTERVAL_SECONDS | No | 300 | Periodic sync interval in seconds |
NODE_ENV | No | — | Set to production to enforce HTTPS for JOPLIN_SERVER_URL |
Note:
JOPLIN_API_TOKENis not a user-facing variable. The entrypoint script automatically extracts it from Joplin's config (joplin config api.token) and exports it for the server. If running natively without the entrypoint, you must setJOPLIN_API_TOKENmanually (runjoplin config api.tokenin your terminal to get it).
Running the Server
# Production (compiled)
pnpm build && pnpm start
# Development (hot reload via tsx watch)
pnpm dev
The server starts the Joplin Data API as a child process, waits for readiness (polling /ping), performs an initial sync, then begins listening on stdio for MCP requests.
MCP Client Configuration (Native / Node.js)
{
"mcpServers": {
"joplin": {
"command": "node",
"args": ["/path/to/joplin-api/dist/server.js"],
"env": {
"JOPLIN_SERVER_URL": "https://joplin.example.com/",
"JOPLIN_USERNAME": "your-email@example.com",
"JOPLIN_PASSWORD": "your-password",
"JOPLIN_API_TOKEN": "<from joplin config api.token>"
}
}
}
}
Testing
# Run all tests
pnpm test
# Watch mode
pnpm test:watch
# Lint
pnpm lint
# Format
pnpm format
Tests use Vitest and cover all modules: config parsing, CLI executor, data client, error classes, sync manager, pagination, MCP schemas, tool handlers, and integration tests against a live Joplin Data API.
Docker
Prerequisites
- Docker and Docker Compose installed on your system
- The
.env.examplefile copied to.envand configured with your Joplin Server credentials
A docker-compose.yml and Dockerfile are included in the repository for containerised deployment.
Building
docker compose build
Running
docker compose up -d
Viewing Logs
docker compose logs -f
Stopping
docker compose down
Environment Variables
Same variables as in the Direct Installation configuration above. Place them in the .env file (which is automatically picked up by docker-compose.yml) or directly in the environment: section of docker-compose.yml.
| Variable | Required | Default | Description |
|---|---|---|---|
JOPLIN_SERVER_URL | Yes | — | Joplin Server URL (e.g., https://joplin.example.com/) |
JOPLIN_USERNAME | Yes | — | Joplin Server username/email |
JOPLIN_PASSWORD | Yes | — | Joplin Server password |
JOPLIN_DATA_API_PORT | No | 41184 | Internal Data API listen port (Joplin ClipperServer hardcoded default) |
LOG_LEVEL | No | info | Log level: debug, info, warn, error, silent |
SYNC_INTERVAL_SECONDS | No | 300 | Periodic sync interval in seconds |
NODE_ENV | No | — | Set to production to enforce HTTPS for JOPLIN_SERVER_URL |
Note:
JOPLIN_API_TOKENis not a user-facing variable. The entrypoint script automatically extracts it from Joplin's config (joplin config api.token) and exports it for the server.
MCP Client Configuration (Docker)
{
"mcpServers": {
"joplin": {
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "joplin-api-mcp"]
}
}
}
How It Works
- Builds from
node:22-bookworm-slimvia a multi-stageDockerfile(build stage compiles TypeScript and runs tests; production stage contains onlydist/and production dependencies) - Runs as non-root
joplinuser - Stores Joplin profile data in a named volume (
joplin_data) - Uses a
socatproxy to expose the Data API externally (ClipperServer hardcodes127.0.0.1:41184; socat proxies0.0.0.0:41185→127.0.0.1:41184) - The host port
41184maps to container proxy port41185(restricted to127.0.0.1on the host) - Healthcheck polls
/pingon the proxy port every 30s
Note: The
deploy.resourcesblock indocker-compose.yml(CPU/memory limits) is only enforced by Docker Swarm. When usingdocker compose up, these limits are silently ignored. For local resource constraints, use--cpusand--memoryflags or set resource limits in your container runtime (e.g., Docker Desktop settings).
Testing with Docker
A dedicated Dockerfile.tests and test service in docker-compose.yml allow running the test suite in a container:
# Build the test image
docker build -f Dockerfile.tests -t joplin-api-tests .
# Run tests
docker run --rm joplin-api-tests
# Or via docker compose
docker compose run --rm tests
Tests use Vitest with v8 coverage (thresholds: 70% statements, 60% branches, 70% functions, 70% lines) and output JUnit XML reports to ./reports/. When running via docker compose, the ./reports directory is mounted into the container so reports persist on the host.
The test suite does not require a running Joplin instance — unit tests use mocks, and integration tests are skipped when the Joplin Data API is unavailable.
Architecture
graph TD
A[AI Client] -->|"MCP stdio"| B[TypeScript MCP Server]
B -->|"TypeScript method calls"| C[JoplinDataClient]
C -->|"HTTP fetch() + Bearer Token"| D[Joplin Data API]
D -->|"Child Process"| E[Joplin SQLite DB]
B -->|"SyncManager"| F[Joplin CLI sync]
F -->|"sync.target 10"| G[Joplin Server]
G -->|"HTTPS"| F
B -->|"SIGTERM cleanup"| D
Layered architecture:
- MCP Client connects via stdio transport to the TypeScript MCP server
- MCP Server exposes 16 tools and delegates data operations to JoplinDataClient
- JoplinDataClient communicates with the Joplin Data API (HTTP, token auth, localhost)
- Joplin Data API runs as a child process spawned by the server, reading/writing the local SQLite database
- SyncManager orchestrates sync via the Joplin CLI (subprocess) against Joplin Server (sync target 10)
- Write operations trigger immediate sync (blocking until the sync completes); periodic sync runs every 5 minutes
Available MCP Tools
Tool Overview
| Tool | Description | Writes? |
|---|---|---|
list_notebooks | List all notebooks/folders | No |
search_notes | Search notes, folders, and tags | No |
read_note | Read a single note by ID | No |
read_notebook | Read a single notebook by ID | No |
read_multinote | Read multiple notes by IDs | No |
read_tags | Get tags for a note | No |
create_note | Create a new note | Yes |
create_folder | Create a new notebook | Yes |
edit_note | Edit an existing note | Yes |
edit_folder | Edit an existing folder | Yes |
create_tag | Create a new tag | Yes |
tag_note | Apply a tag to a note | Yes |
untag_note | Remove a tag from a note | Yes |
delete_note | Delete a note | Yes |
delete_folder | Delete a folder | Yes |
sync | Manually trigger sync | No |
Input / Output Schemas
All tool input is validated through Zod schemas. Below are the expected input fields and return types.
Read Tools
| Tool | Input | Output |
|---|---|---|
list_notebooks | {} | Folder[] |
search_notes | { query: string (1–1000 chars), type?: "note" | "folder" | "tag" } | SearchResult[] |
read_note | { note_id: string (32-char hex) } | Note |
read_notebook | { notebook_id: string (32-char hex) } | Folder |
read_multinote | { note_ids: string[] (array of 32-char hex IDs) } | { notes: Note[], errors: { note_id, error }[] } |
read_tags | { note_id: string (32-char hex) } | Tag[] |
Write Tools
| Tool | Input | Output |
|---|---|---|
create_note | { title (1–500 chars), parent_id?, body? (max 1 MB), author? (max 200), source_url? (validated URL), is_todo? (boolean | number 0/1), todo_due? (unix ms) } | Note |
create_folder | { title (1–500 chars), parent_id?, icon? (max 100) } | Folder |
edit_note | { note_id, title?, parent_id?, body?, author? (max 200), source_url? (validated URL), is_todo? (boolean | number 0/1), todo_due? (unix ms) } | Note |
edit_folder | { folder_id, title?, parent_id?, icon? (max 100) } | Folder |
create_tag | { title (1–200 chars) } | Tag |
tag_note | { note_id, tag_id } | NoteTag |
untag_note | { note_id, tag_id } | { success: true } |
Delete Tools
| Tool | Input | Output |
|---|---|---|
delete_note | { note_id } | { success: true } |
delete_folder | { folder_id } | { success: true } |
Sync Tool
| Tool | Input | Output |
|---|---|---|
sync | {} | { status: "idle" | "syncing", lastSyncTime: string | null } |
Error Response Format
When a tool execution fails, the MCP server returns a response with isError: true and a content array containing a single text entry:
{
"content": [{ "type": "text", "text": "Error message describing the failure" }],
"isError": true
}
Validation errors (Zod schema mismatch) are logged at warn level and include the specific field path and reason, for example:
Validation error: note_id: Expected 32-character hex ID
Execution errors (API failures, timeouts, etc.) are logged at error level and include the tool name and error message. See the Error Handling section for the full error class hierarchy.
Sync Behaviour
- Initial sync: Runs on startup via SyncManager before accepting MCP requests
- Periodic sync: Every 5 minutes (configurable via
SYNC_INTERVAL_SECONDS) - Write-triggered sync: After every create/update/delete/untag operation (immediate, blocking until sync completes)
- Conflict resolution: Remote always wins (Joplin CLI built-in behaviour; conflicted copies are flagged in Joplin)
- Serialized queue: Prevents
SQLITE_BUSYerrors by serializing sync operations
Security Considerations
Token Management
The Joplin Data API uses bearer token authentication. The token is obtained automatically on startup via a POST /auth request and is stored in a GuardedString wrapper:
GuardedStringstores the raw value in a private#valuefield, making it inaccessible throughtoString(),toJSON(), or template-literal coercion — all such operations return'[REDACTED]'- The only way to access the actual value is via the explicit
.valueproperty - This prevents accidental leakage through logging, serialisation, or error messages
- Tokens are proactively refreshed 60 seconds before expiry and re-fetched automatically on 401 responses
TLS Requirements for Production
- The Joplin Data API always binds to
127.0.0.1(localhost-only), so TLS between the server and the Data API is unnecessary — traffic never leaves the machine - The Joplin Server URL (
JOPLIN_SERVER_URL) must use HTTPS in production — this is enforced by the config schema (seesrc/config.ts). HTTP is only allowed whenNODE_ENVis not set toproduction - Joplin CLI sync traffic to Joplin Server is plain HTTP by default; ensure your Joplin Server is deployed behind a TLS-terminating reverse proxy
Localhost-Only Defaults
- The Joplin ClipperServer hardcodes binding to
127.0.0.1, making it unreachable from outside the container directly. A socat TCP proxy inside the container forwards the proxy port (JOPLIN_DATA_API_PORT + 1) to127.0.0.1:JOPLIN_DATA_API_PORT, started after ClipperServer readiness - The MCP server communicates over stdio transport — there is no network port exposed for MCP traffic
- The
docker-compose.ymlmaps the host port (JOPLIN_DATA_API_PORT, default41184) to the container's proxy port (JOPLIN_DATA_API_PORT + 1, i.e.,41185). This makes the Data API accessible athttp://localhost:41184on the host machine, but not from other network hosts (bound to127.0.0.1) - If you do not need host-side access to the Data API, remove the
ports:block fromdocker-compose.ymlto keep the port container-internal only
Token Rotation Best Practices
- The Joplin Data API issues tokens with a configurable expiry (default ~55 minutes, controlled by the Joplin Data API server)
- The client automatically refreshes the token before expiry and on 401 responses
- If a token compromise is suspected, rotate the Joplin Server credentials (
JOPLIN_PASSWORD) and restart the container — a new token will be issued on the nextPOST /authcall
CLI Argument Sanitization
All Joplin CLI subcommands executed via CliExecutor are protected by two layers of defence:
- Subcommand whitelist — Only a predefined set of subcommands (sync, config, ls, cat, etc.) is allowed. Unknown subcommands are rejected before execution
- Shell metacharacter blocking — Arguments containing
;,|,&,$,`,(,),{,},<,>,\nare rejected
These checks are defence-in-depth on top of Node.js execFile, which does not spawn a shell.
Error Handling
Error
├── ConfigError # Missing/invalid environment variables
├── CliError # Joplin CLI subprocess failure
│ └── Properties: result { stdout, stderr, exitCode }
├── DataApiError # Joplin Data API HTTP error
│ ├── statusCode: number
│ ├── responseBody?: string
│ ├── NotFoundError (404) # Resource not found
│ ├── ConflictError (409) # Resource modified since fetch
│ ├── ValidationError (400)# Invalid input
│ └── AuthError (401) # Authentication failed
└── FatalError # Fatal/unexpected error
├── cause?: unknown
└── exitCode: number (default 1)
Rate Limiting
The internal Joplin Data API HTTP client (JoplinDataClient) enforces a configurable concurrency limit to prevent overwhelming the Data API process:
- Default max concurrency: 5 concurrent requests
- Configurable via:
maxConcurrencyconstructor parameter onJoplinDataClient - Behaviour: When the limit is reached, additional requests are queued and executed as soon as a slot becomes available
- Scope: All Data API calls (list, get, create, update, delete, search) share the same concurrency pool
- Per-tool: Individual tool calls make a single Data API request, so concurrency is only relevant under parallel MCP requests
Troubleshooting
Authentication Failures
Symptom: MCP tools return "Authentication failed" or AuthError.
Causes and fixes:
| Cause | Fix |
|---|---|
Invalid JOPLIN_PASSWORD in .env | Verify the password matches your Joplin Server account |
| Token expired before refresh | Check that the system clock is synchronised (NTP). The client refreshes tokens proactively, but clock drift can cause premature expiry |
| Joplin Server unreachable | Ensure JOPLIN_SERVER_URL is correct and the server is running. Verify TLS certificate if using HTTPS |
| Data API not ready | Wait for the "Data API server is ready" log line before sending requests |
Diagnostic steps:
- Check container logs:
docker compose logs - Look for entries containing
"Failed to obtain Joplin API token"or"AuthError" - Verify credentials by curling the Joplin Server API directly
Sync Conflicts
Symptom: Logs contain "Sync conflicts detected — remote version retained" warnings.
Behaviour: The system uses a remote-wins conflict resolution strategy. Local changes always yield to remote versions.
What to do:
- Conflict notes are flagged in Joplin as conflicted copies. Check for them using the Joplin desktop/client app
- You can programmatically check conflict count via
CliExecutor.checkConflicts() - To resolve, review the conflicted notes in Joplin and manually merge or delete them
Timeout Issues
Symptom: CLI commands fail with "joplin CLI timed out after Nms".
Causes and fixes:
| Cause | Fix |
|---|---|
| Large initial sync (many notes/resources) | Increase SYNC_INTERVAL_SECONDS or let the initial sync complete — subsequent syncs are incremental |
| Joplin Server slow to respond | Check Joplin Server performance (CPU, memory, database). Ensure network latency is low |
| CLI command timeout too short | The default timeout is 60 seconds; for extremely large operations, this can be adjusted in CliExecutor.exec() |
CLI Execution Errors
Symptom: CliError with exit code, stdout, and stderr details.
Common causes:
- Missing
joplinbinary: ThejoplinCLI must be installed in the container and available onPATH. The Dockerfile handles this, but verify if using a custom setup - Config not set: The entrypoint script configures
sync.target 10and server credentials. If skipped,joplin syncwill fail with a configuration error - Permission errors: Ensure the Joplin CLI config directory (
~/.config/joplin) is writable
Rate Limiting
Symptom: Requests are queued or take longer than expected, but no errors are thrown.
Behaviour: The JoplinDataClient enforces a maximum of 5 concurrent API requests (configurable). Additional requests are queued and processed sequentially as slots open up.
If you hit concurrency limits:
- Reduce the number of parallel MCP tool calls from your AI client
- The concurrency limit is a constructor parameter on
JoplinDataClientinsrc/data-client.ts. Increase it if you have a specific need for higher parallelism, but be aware of the Data API's own capacity
Development
Commands
pnpm install # Install dependencies
pnpm dev # Run in development mode with hot reload (tsx watch)
pnpm build # Compile TypeScript (tsc)
pnpm start # Run compiled server (node dist/server.js)
pnpm test # Run tests (vitest)
pnpm test:watch # Run tests in watch mode
pnpm lint # Lint source code (eslint)
pnpm format # Format source code (prettier --write)
Project Structure
src/
├── server.ts # Main entry point: orchestrates startup & lifecycle
├── config.ts # Zod-based environment config parsing
├── logger.ts # Pino structured logger
├── cli-executor.ts # Joplin CLI subprocess wrapper
├── sync-manager.ts # Serialized sync queue orchestrator
├── data-client.ts # Joplin Data API HTTP client (26 methods, token auth)
├── api-types.ts # TypeScript type definitions for Joplin API
├── errors.ts # Typed error class hierarchy
├── guarded-string.ts # Secure string wrapper (prevents accidental secret leakage)
├── pagination.ts # Pagination helpers (clampLimit, fetchAllPages)
└── mcp/
├── server.ts # MCP stdio server setup
├── schemas.ts # Zod validation schemas for all 16 tools
├── tools.ts # 16 tool handler implementations
└── tool-registry.ts # Tool registration and dispatch
tests/
├── cli-executor.test.ts # CLI executor tests
├── config.test.ts # Config parser tests
├── data-client.test.ts # Data API client tests
├── errors.test.ts # Error class hierarchy tests
├── integration.test.ts # Integration tests against live Joplin Data API
├── logger.test.ts # Logger tests
├── pagination.test.ts # Pagination helper tests
├── server.test.ts # Server tests
├── sync-manager.test.ts # Sync manager tests
└── mcp/
├── schemas.test.ts # Zod schema validation tests
├── server.test.ts # MCP server lifecycle tests
├── tool-registry.test.ts # Tool registration & dispatch tests
└── tools.test.ts # Tool handler tests
docs/
├── ARCHITECTURE.md # Architecture documentation with Mermaid diagrams
├── CODEREVIEW.md # Code review notes and findings
├── PROMPT.md # AI prompt documentation
└── TASK_LOG.md # Workspace action log
scripts/
└── smoke-test.sh # Docker container smoke test (checks container up + Data API /ping)
Startup & Shutdown Pipeline
- Validate environment variables — Entrypoint script checks
JOPLIN_SERVER_URL,JOPLIN_USERNAME,JOPLIN_PASSWORD - Configure Joplin CLI — Sets
sync.target 10and server credentials in Joplin CLI config - Start TypeScript server —
exec node dist/server.js(foreground) - Parse config — Zod schema validates all env vars with defaults
- Initialize logger — Pino structured logger at configured level
- Start Joplin Data API — Spawned as child process on configurable port (default: 41184)
- Wait for readiness — Polls
/pingendpoint (up to 5 minutes, 300 retries at 1s intervals) - Verify connectivity — Pings Data API to confirm auth and version
- Perform initial sync — SyncManager runs full sync via Joplin CLI
- Start periodic sync — Interval-based sync loop begins
- Initialize tool registry — Registers all 16 MCP tool handlers
- Start MCP server — Blocks on stdio transport, serving MCP requests
- Handle signals — On
SIGTERM/SIGINT: stop periodic sync, kill Data API process (SIGTERM → 2s grace → SIGKILL), exit
Key Design Decisions
- Data API over CLI for data operations — Avoids fragile CLI output parsing; uses structured HTTP API with typed responses
- No HTTP framework — MCP SDK provides stdio transport;
fetch()(built-in Node.js) handles Data API calls - Write-through sync — Write tools trigger immediate sync so Joplin Server is always up-to-date
- Serialized sync queue — Prevents concurrent sync calls causing
SQLITE_BUSYerrors - Remote-wins conflict resolution — Delegated to Joplin CLI built-in behaviour; local changes always yield to remote
- Token lifecycle — Auth token obtained via
POST /auth, reused with 60-second proactive refresh buffer before 55-minute expiry, re-fetched on 401 responses
License
MIT