内容
# 📓 Joplin MCP 服务器
*一个模型上下文协议（MCP）服务器，将您的 [Joplin](https://joplinapp.org/) 笔记本转化为 LLM 可以使用的工具 — 读取、搜索、编写和组织笔记，并直接从截图中提取 OCR 文本。*
---
## 这是什么？
[Joplin](https://joplinapp.org/) 自带了一个本地 **网页剪辑器 / 数据 API** (`http://127.0.0.1:41184`)，可以通过普通的 HTTP 操作整个应用程序 — 笔记、笔记本、标签、附件。
该项目将该 API 封装为 **[MCP](https://modelcontextprotocol.io/) 服务器**，因此任何兼容 MCP 的客户端（Claude Code、Claude Desktop 或您自己的代理）都可以：
- 浏览您的笔记本树并列出任意笔记本中的笔记
- 读取笔记的完整 Markdown 正文
- 在您的整个 Joplin 数据库中进行全文搜索
- 创建、重命名、移动和删除笔记 **和** 笔记本
- 将嵌入的附件（截图、PDF、PoC 文件等）下载到磁盘以便查看
- **从图像/PDF 附件中提取 OCR 文本** — 在不打开截图的情况下读取其中的内容
无需在 Joplin 本身安装插件 — 所有操作都通过已内置的数据 API 进行。
---
## 功能
| 工具 | 功能描述 |
| --- | --- |
| `list_notebooks` | 列出所有笔记本（文件夹），包含 `id`、`title` 和 `parent_id` |
| `create_notebook` | 创建一个新的笔记本，可选地嵌套在父笔记本下 |
| `update_notebook` | 重命名和/或移动笔记本到不同的父笔记本 |
| `delete_notebook` | 删除笔记本，包括其中的所有内容（移动到 Joplin 的回收站） |
| `list_notes` | 列出笔记，可选地限定在一个笔记本中，分页显示 |
| `search_notes` | 使用 Joplin 的原生搜索语法进行全文搜索（`title:`、`tag:`等） |
| `get_note` | 获取笔记的完整 Markdown 正文 + 元数据 |
| `create_note` | 创建新的笔记（标题、Markdown 正文、目标笔记本、待办事项标志） |
| `update_note` | 重命名、编辑和/或移动笔记（也编辑正文/待办事项状态） |
| `delete_note` | 删除笔记（移动到 Joplin 的回收站） |
| `get_resource_info` | 获取附件文件的元数据（MIME 类型、扩展名、大小） |
| `get_resource_file` | 将附件的原始字节下载到本地路径，以便打开/查看 |
| `get_resource_ocr_text` | 读取 Joplin 内置的 OCR 引擎识别的图像/PDF 附件中的文本 |
---
## 要求
- **[Joplin 桌面版](https://joplinapp.org/download/)**，正在运行，且启用了网页剪辑器服务
- Joplin **网页剪辑器授权令牌**
- **Python 3.12+**
- **[uv](https://docs.astral.sh/uv/)**（推荐）— 或普通的 `pip`
---
## 安装
```bash
git clone https://github.com/<your-username>/joplin-mcp.git
cd joplin-mcp
# 使用 uv（推荐，使用已提交的 uv.lock 进行可复制安装）
uv sync
# — 或使用普通的 pip —
pip install "httpx>=0.28.1" "mcp[cli]>=1.28.1"
```
### 1. 在 Joplin 中启用网页剪辑器服务
`Joplin → 工具 → 选项 → 网页剪辑器` → 打开。注意显示的端口（默认为 `41184`）。
### 2. 获取访问令牌
同一屏幕 → **"高级选项"** → **"复制令牌"**。请保密此令牌 — 拥有它的人可以完全读写您的整个笔记本。
### 3. （可选）启用 OCR，如果您希望 `get_resource_ocr_text` 返回内容
`Joplin → 工具 → 选项 → 常规` → 启用 **"启用文档文本提取（OCR）"**。Joplin 需要一些时间来处理您启用后现有的附件 — 请检查工具返回的 `ocr_status` 字段（`0`/`1` = 队列中，`2` = 处理中，`3` = 完成，`4` = 错误，参见 `ocr_error`）。
---
## 配置
服务器读取两个环境变量：
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `JOPLIN_TOKEN` | ✅ 是 | — | 您的网页剪辑器授权令牌 |
| `JOPLIN_BASE_URL` | 否 | `http://127.0.0.1:41184` | Joplin 网页剪辑器 API 的基准 URL |
---
## 与 MCP 客户端一起使用
将以下内容添加到客户端的 MCP 配置中（例如 Claude Code 的 `.mcp.json` 或 Claude Desktop 配置文件）：
```json
{
"mcpServers": {
"joplin": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/joplin-mcp", "python", "server.py"],
"env": {
"JOPLIN_TOKEN": "<your-joplin-web-clipper-token>",
"JOPLIN_BASE_URL": "http://127.0.0.1:41184"
}
}
}
}
```
> 不使用 `uv`？请将 `command`/`args` 替换为 `"command": "python", "args": ["/absolute/path/to/joplin-mcp/server.py"]`。
重启/重新连接您的 MCP 客户端，`joplin` 工具应该会出现。
---
## 连接后示例提示
- *"列出我的 Joplin 笔记本。"*
- *"在我的笔记中搜索 'react devtools'。"*
- *"调出标题为 X 的笔记并总结它。"*
- *"下载附加到此笔记的截图，以便我可以查看它。"*
- *"从我上周扫描的 PDF 中提取了什么文本？"*
---
## 安全注意事项
- 网页剪辑器令牌授予 **完全的读写访问权限** 到您的整个 Joplin 数据库 — 请像对待密码一样保护它。永远不要将其提交到存储库中。
- 服务器默认情况下只与 `127.0.0.1` 通信（您的本地 Joplin 实例）— 它不设计为通过网络公开。
- `delete_note` 会将笔记移动到 Joplin 的回收站（可恢复），除非您在 Joplin 设置中禁用了回收站。
---
## 已知限制 / 路线图
本项目涵盖了日常笔记/笔记本/附件工作流程，但并未涵盖 Joplin 数据 API 的所有方面：
- ❌ 标签 — 无列表/创建/分配标签支持
- ⚠️ 资源 — 无附件上传/删除（仅读取 + OCR 文本）
- ❌ 笔记修订历史
如果您需要其中之一，欢迎提交 PR。
---
## 项目结构
```
joplin-mcp/
├── server.py # MCP 服务器 — 所有工具都位于此处
├── pyproject.toml # 项目元数据 + 依赖项
├── uv.lock # 锁定依赖项版本（uv）
├── .python-version # 为 uv 固定的 Python 版本
├── .gitignore
├── LICENSE
└── README.md
```
---
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
