Provides tools for managing notes, notebooks, tags, to-dos, resources, and search within Joplin, including CRUD operations, content editing, tagging, and workflow automation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@joplin-mcp create a note titled 'Meeting Notes' in the 'Work' folder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
基于 FastMCP 的 MCP 服务器，将 Joplin REST API 转换为 MCP 工具，使 LLM 能够直接与 Joplin 笔记应用交互。
Task-Centric 设计：v2 版本采用以任务为中心的设计理念，工具语义清晰，参数精简
单一职责：每个工具只做一件事，工具名称直接表达意图
最小参数：只包含完成该任务必需的参数，减少 LLM 填写负担
无状态设计：不引入额外数据库，所有数据存储在 Joplin 中
配置驱动：通过环境变量管理配置
Related MCP server: Joplin MCP Server
包 | 用途 |
fastmcp | MCP 框架 |
httpx | 异步 HTTP 客户端 |
pydantic | 数据验证 |
pydantic-settings | 配置管理 |
打开 Joplin 桌面应用
进入 工具 → 选项 → Web Clipper
复制显示的 Token
pip install -e .开发模式（包含测试工具）：
pip install -e ".[dev]"复制 .env.example 为 .env：
cp .env.example .env编辑 .env，填入你的 Joplin Token：
JOPLIN_MCP_JOPLIN__TOKEN=your_api_token_herefastmcp run src/joplin_mcp/server.py# 采用streamable http方式
fastmcp run src/joplin_mcp/server.py --transport http --port 8881在 Claude Desktop 配置中添加：
{
"mcpServers": {
"joplin": {
"command": "fastmcp",
"args": ["run", "path/to/joplin-mcp/src/joplin_mcp/server.py"],
"env": {
"JOPLIN_MCP_JOPLIN__TOKEN": "your_token"
}
}
}
}工具 | 参数 | 描述 |
|
| 创建普通笔记 |
|
| 剪藏网页 |
|
| 创建带图片的笔记 |
|
| 获取单个笔记详情 |
|
| 获取笔记列表 |
|
| 获取最近更新的笔记 |
|
| 移动笔记到另一个笔记本 |
|
| 复制笔记 |
|
| 将笔记移至回收站 |
|
| 从回收站恢复笔记 |
|
| 永久删除笔记 |
|
| 归档笔记 |
工具 | 参数 | 描述 |
|
| 仅更新标题 |
|
| 仅更新正文 |
|
| 追加内容到末尾 |
|
| 在开头添加内容 |
|
| 替换文本 |
工具 | 参数 | 描述 |
|
| 创建待办事项 |
|
| 标记待办为已完成 |
|
| 取消完成待办 |
|
| 设置截止时间 |
|
| 清除截止时间 |
|
| 获取待办列表 |
工具 | 参数 | 描述 |
|
| 获取笔记本列表 |
|
| 获取单个笔记本 |
|
| 创建笔记本 |
|
| 创建子笔记本 |
|
| 重命名笔记本 |
|
| 移动笔记本 |
|
| 设置图标 |
|
| 获取完整树形结构 |
|
| 获取笔记本内的笔记 |
|
| 移至回收站 |
|
| 从回收站恢复 |
|
| 永久删除 |
工具 | 参数 | 描述 |
|
| 获取所有标签 |
|
| 获取单个标签 |
|
| 创建标签 |
|
| 重命名标签 |
|
| 合并标签 |
|
| 删除标签 |
|
| 获取具有某标签的笔记 |
|
| 为笔记添加标签 |
|
| 从笔记移除标签 |
|
| 设置笔记标签（替换） |
|
| 获取笔记的所有标签 |
工具 | 参数 | 描述 |
|
| 获取资源列表 |
|
| 获取资源详情 |
|
| 下载资源文件 |
|
| 获取关联的笔记 |
|
| 删除资源 |
工具 | 参数 | 描述 |
|
| 搜索笔记 |
|
| 搜索笔记本 |
|
| 搜索标签 |
工具 | 参数 | 描述 |
|
| 批量移动笔记 |
|
| 批量删除笔记 |
|
| 批量添加标签 |
|
| 批量完成待办 |
|
| 整理笔记到文件夹 |
|
| 处理待办（完成/延期/转笔记） |
|
| 获取指定日期的笔记回顾 |
|
| 获取本周笔记回顾 |
变量 | 默认值 | 描述 |
| (必填) | Joplin API Token |
| localhost | Joplin 主机 |
| 41184 | Joplin 端口 |
| Joplin | 服务器名称 |
| false | 调试模式 |
joplin-mcp/
├── pyproject.toml # 项目配置
├── .env.example # 环境变量模板
├── README.md # 项目说明
├── src/joplin_mcp/
│ ├── server.py # FastMCP 服务器入口
│ ├── config.py # 配置管理
│ ├── client.py # Joplin API 客户端
│ ├── exceptions.py # 自定义异常
│ └── tools/
│ ├── __init__.py
│ ├── notes.py # 笔记核心操作 (12 个工具)
│ ├── notes_content.py # 笔记内容编辑 (5 个工具)
│ ├── folders.py # 笔记本管理 (12 个工具)
│ ├── tags.py # 标签管理 (11 个工具)
│ ├── resources.py # 资源管理 (5 个工具)
│ ├── search.py # 搜索 (3 个工具)
│ ├── todos.py # 待办任务 (6 个工具)
│ └── workflows.py # 复合工作流 (8 个工具)
└── docs/
├── v2_design.md # v2 设计文档
└── joplin_api.md # Joplin API 文档安装开发依赖：
pip install -e ".[dev]"运行测试：
pytest代码检查：
ruff check src/维度 | v1 | v2 |
设计思维 | API 映射 | 任务导向 |
工具数量 | 17 个 | 62 个 |
参数数量 | 多可选参数 | 最小必需参数 |
工具命名 | CRUD 风格 | 语义化风格 |
LLM 负担 | 高（需筛选参数） | 低（参数即意图） |
移动笔记到工作笔记本：
v1:
update_note(note_id="abc123", folder_id="xyz789")v2:
move_note(note_id="abc123", folder_id="xyz789")标记待办为已完成：
v1:
update_note(note_id="abc123", todo_completed=1710864000000)v2:
complete_todo(note_id="abc123") # 自动处理时间戳This server cannot be deployed
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
