内容
joplin-mcp
基于 Go 的 MCP 服务器，连接 AI 助手到 Joplin 桌面端，实现完整的笔记管理。
## 功能特点
27 种工具涵盖笔记、文件夹、标签、搜索、批量操作、导出/导入和资源管理 — 所有这些都可供任何与 MCP 兼容的助手（例如 Claude）访问。
- **笔记**：创建、读取、更新、删除、批量读取
- **搜索**：全文搜索，支持正文预览
- **文件夹**：列出、创建、重命名、删除（支持嵌套树形结构，自动计算路径）
- **标签**：列出、应用、移除、删除、按标签查询笔记
- **批量操作**：移动笔记、批量添加标签、合并笔记
- **导出**：导出 文件、从目录批量导入
- **资源管理**：列出、查看、下载和上传附件
实用工具**：连接性检查、导入单个 Markdown 文件
## 前
- [Joplin端](https://joplinapp.org/) 已安装并运行
- Web 剪贴板已启用设置 → Web 剪 → 启用 Web 剪贴板服务**
- 从 Web 剪贴板设置页面复制您的 API token
## 安装
### Homebrew
brew tap wickes1/tap
brew install jocp
```
### Gobash
go install github.comes1/joplin-mcp@latest
```
### 二进制文件
从 [GitHub Releases](https://github.com/wickes1/joplin-mcp/releases) 下载预编译的二进制文件。
支持的平台：macOS (Intel/Apple Silicon)、Linux (x86_64/arm64)、Windows (x86_64/arm64)。
## 配置
在您的 `.mcp.json`（或 Claude Code 的 MCP 配置）中添加：
```json
{
"mcpServers": {
"joplin": {
"command": "joplin-mcp",
"env": {
"JOPLIN_TOKEN": "your-token-here",
"JOPLIN_HOST": "localhost",
"JOPLIN_PORT": "41184"
}
}
}
}
```
### 环境变量
| 变量名 | 默认值 | 描述 |
|--------|---------|-------------|
| `JOPLIN_TOKEN` | （必填） | Joplin Web 剪贴板 API token |
| `JOPLIN_HOST` | `localhost` | Joplin API 主机 |
| `JOPLIN_PORT` | `41184` | Joplin API 端口 |
| `JOPLIN_LOG_LEVEL` | `info` | 日志级别：`debug`、`info`、`warn`、`error` |
| `JOPLIN_READ_TIMEOUT` | `30` | GET 操作的超时时间（秒） |
| `JOPLIN_WRITE_TIMEOUT` | `120` | POST/PUT/DELETE 操作的超时时间（秒） |
> **安全性**：请勿将 `JOPLIN_TOKEN` 提交到版本控制。在 macOS 上，可以将其存储在 Keychain 中，并通过包装脚本注入。
## 工具参考
### 笔记（6 种工具）
| 工具 | 描述 |
|------|-------------|
| `list_notes` | 列出笔记，可选按文件夹过滤。返回精简的笔记和 `has_more` 标志。 |
| `get_note` | 通过 ID 获取单个笔记，包含完整正文和标签。 |
| `get_notes` | 批量读取最多 50 个笔记，失败的查找包含为错误条目。 |
| `create_note` | 创建新笔记。可选自动创建文件夹并应用标签。 |
| `update_note` | 更新的标题、正文、文件夹或待办状态。如果未找到，`folder_name` 自动 |
| `delete_note` ID 删除笔记。默认移动到回收站；设置 `permanent=true绕过回收站。 |
### 搜索（1 种工具）
| 工具 | 描述------|-------------|
| `search_notes` | 对所有笔记进行全文搜索。返回预览笔记（200正文预览）和 `` 标志。 |
### 文件夹（4 种工具）
| 工具 | 描述 |
-------------|
| `list_folders` | 列出所有文件夹套树形结构，包含（例如 `工作/1`）。 |
| `create_folder` | 创建新文件夹，可选嵌套在父文件夹下。 |
| `update_folder` | 重命名或移动文件夹。 |
| `delete_folder` | 通过 ID 删除文件夹。默认移动到回收站；设置 `permanent=true` 可绕过回收站。 |
### 标签（5 种工具）
| 工具 | 描述 |
|------|-------------|
| `list_tags` | 列出 Joplin 库中的所有标签。 |
| `tag_note` | 将标签应用于笔记。如果标签不存在，则自动创建（不区分大小写）。 |
| `untag_note笔记中移除标签（不区分大小写标签查找）。 |
| `delete_tag` | 通过 ID 删除标签。从所有笔记中移除。 |
| `get_notes_by_tag` | 获取与标签名称关联的笔记（不区分大小写）。返回精简的笔记和 `has_more` 标志。 |
### 批量3 种工具）
| 工具 | 描述 |
|------|-------------|
| `batch_move_notes` | 将最多 100 个笔记移动到目标文件夹。 |
| `batch_tag_notes` | 同时为最多 100 个笔记添加或移除标签。添加时自动创建标签。 |
| `merge_notes` | 获取最多 50 个笔记，连接其正文并创建新的合并笔记。 |
### 导出/导入（2 种工具）
| 工具 | 描述 |
|------|-------------|
| `export_notes` | 将 Joplin 笔为 Markdown 文件，保留文件夹，可选 YAML 前置 |
| `batch_import_markdown` | 遍历目录中的 `.md` 文件，并将每个文件导入为 Joplin 笔记，可选保留目录结构为文件夹。 |
### 资源管理（4 种
| 工具 ||------|-------------|
| `list_resources` | 列plin附件）。返回一和 `has_more` |
| `get | 通过 ID 获取单个 资源（附件）的元数据。 |
| `download_resource 将 Joplin 资源（文件下载到本地磁盘路径。 |
| `upload_resource` | 将本地文件上传为 Joplin 资源。返回嵌入 ID：`` 或 `[name](:/id)`。 |
### 实用工具（2 种工具）
| 工具 | 描述 |
|------|-------------|
| `import_markdown` | 将单个 Markdown（`.md`）文件导入 Joplin 为笔记。从第一个 `#` 标题或文件名中提取标题。 |
| `get_status` | 检查 Joplin 连接性并返回库统计信息（文件夹数量、标签数量、端口）。 |
## 响应设计
工具遵循 **精简/完整/预览** 模式以降低 token 使用量：
- **精简**（列表操作）：`idtitle`、`parent、`folder_title`、`is_todo`、`updated_time`。用于浏览，无需获取笔记正文。
- **完整**（_note`、`get_notes`）：所有精简字段加上 `body`、`created_time`、`todo_completed` 和 `tags[]`。在需要内容时使用。
- **预览**（搜索）：精简字段加上正文的前 200 个字符。通常足以在不跟进 `get_note` 调用情况下判断相关性。
写操作（`create_note`、`update_note` 等）返回精简响应；读操作（`get_note`、`get_notes`）返回完整响应。
## 许可证
MIT
