Joplin MCP

一个 MCP 服务器，将 Joplin 的笔记集合以工具集的形式暴露出来，并作为运行在 Cloudflare Workers 上的有状态代理工作。把 MCP 客户端（如 Claude）指向已部署的端点，它就能浏览笔记本和笔记，并直接对你的 Joplin 实例创建、更新、删除笔记和笔记本。

工作原理

每次工具调用都会直达你正在运行的实例上的 Joplin Data API——中间没有索引或缓存。Joplin Data API 本身绝不暴露到公网：Worker 通过基于 Cloudflare Tunnel 的 Workers VPC Service 绑定，在私有网络中访问它。

MCP client ──HTTP/SSE──► Worker (/mcp) ──► JoplinMCP (Durable Object)
                                                  │
                          JoplinClient ──► JOPLIN_VPC (Workers VPC Service)
                                                  │
                          Cloudflare Tunnel ──► Joplin Data API (LAN-only)

JoplinMCP 是一个托管在 Durable Object 上的 McpAgent。

Related MCP server: Capacities MCP Worker

工具

每个接受笔记或笔记本的工具，既接受 名称，也接受 32 字符的十六进制 ID，因此调用代理不需要为了查询 ID 而多花一次往返。名称是模糊匹配的（大小写、重音、标点和词序都被忽略）；当名称确实有歧义时，工具会返回候选结果及其 ID，而不会自行猜测。

回收站中的笔记和笔记本，会从所有结果中排除——列表、搜索和直接读取都一样。

减少往返

工具接口的设计让代理能够用尽可能少的调用次数就找到目标笔记。按名称读取笔记只需要一次调用，而不是三次：

list_notebooks → list_notes → get_note      ⟶   get_note { note: "grocery list" }

向笔记追加一行也只需要一次调用，而不是两次，因为 append 在服务端完成了读取-修改-写入：

get_note → update_note { body: <whole note> }  ⟶  update_note { note: "grocery list", append: "- milk" }

名称解析走的是 Joplin 自己的搜索索引，因此通常一次 API 调用就可以完成；只有搜索为空时（比如有拼写错误，或全文索引对标题分词方式比较特殊），才会构建本地标题索引。笔记本列表会缓存在 Durable Object 中，所以解析笔记本名称通常没有额外成本。

设置

npm install

部署前，你的 Joplin Data API 需要能够通过 Cloudflare Tunnel 被访问，并注册为 Workers VPC Service：

npx wrangler vpc service create joplin-data-api \
  --type http \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --hostname <JOPLIN_HOST_ON_YOUR_LAN> \
  --http-port <JOPLIN_PORT>

然后把得到的 service ID 绑定到 wrangler.jsonc：

"vpc_services": [
  { "binding": "JOPLIN_VPC", "service_id": "<service-id-from-above>", "remote": true }
]

JOPLIN_API_TOKEN（一个 Joplin Data API 令牌）从 Cloudflare 的 Secrets Store 读取，而不是普通的 Wrangler secret。每个账户创建一次，之后就可以在多个 Worker 之间复用：

wrangler secrets-store secret create <store-id> \
  --name joplin-token --scopes workers --remote

接着在 wrangler.jsonc 中通过 secrets_store_secrets 绑定它：

"secrets_store_secrets": [
  { "binding": "JOPLIN_API_TOKEN", "store_id": "<store-id>", "secret_name": "joplin-token" }
]

本地开发时，再创建一个同名的本地 secret（不要加 --remote），这样 wrangler dev 才有值可读取。

默认笔记本

需要笔记本的工具会回退到 wrangler.jsonc 中 JOPLIN_DEFAULT_NOTEBOOK 变量指定的那个笔记本，默认是 "Default"。把它指向你希望新笔记落到的笔记本；如果不存在同名的笔记本，工具会如实说明，不会任选一个。

完整的架构与绑定参考，见 CLAUDE.md。

开发

npm run dev         # wrangler dev — local development with hot reload
npm run test        # vitest run
npm run typecheck   # tsc --noEmit

部署

npm run deploy

或者也可以把这个仓库连接到一个 Cloudflare Worker，通过 Git 进行部署。两种方式都一样：账户的 Secrets Store 中必须存在 joplin-token secret——它绝不会被保存在仓库内。

技术栈

• Cloudflare Workers + Durable Objects（SQLite 存储）

• Cloudflare Agents SDK（agents/mcp）

• MCP TypeScript SDK

• TypeScript、Zod（用于工具输入）、Schema ）、Vitest（用于测试）