Joplin (Rust)

基于 Rust 和官方 MCP SDK (rmcp) 实现的 Joplin MCP 服务器。

功能特性

• 笔记管理: 创建、读取、更新、删除笔记
• 待办事项: 创建待办、标记完成、列表查询
• 笔记本管理: 创建、重命名、移动、删除笔记本
• 标签管理: 创建、重命名、删除标签，为笔记添加/移除标签
• 资源管理: 上传、下载、删除附件
• 搜索: 搜索笔记、笔记本、标签
• 双传输模式: 支持 stdio 和 HTTP 两种传输方式

快速开始

1. 获取 Joplin API Token

1. 打开 Joplin 桌面应用
2. 进入 工具 → 选项 → Web Clipper
3. 复制显示的 Token

2. 配置环境变量

复制 .env.example 为 .env 并填写配置：

cp .env.example .env

编辑 .env：

JOPLIN_TOKEN=your_api_token_here
JOPLIN_HOST=localhost
JOPLIN_PORT=41184

3. 编译

cargo build --release

4. 运行

stdio 模式（默认）：

./joplin-mcp
# 或显式指定
./joplin-mcp --stdio

HTTP 模式：

./joplin-mcp --http
# 自定义地址和端口
./joplin-mcp --http --host 127.0.0.1 --port 8080

命令行参数

传输模式参数

参数	描述	默认值
--stdio	使用 stdio 传输模式（默认）	-
--http	使用 HTTP 传输模式	-
--host <HOST>	HTTP 服务器监听地址（仅 HTTP 模式）	0.0.0.0
--port <PORT>	HTTP 服务器监听端口（仅 HTTP 模式）	3000

Joplin 连接参数

参数	描述	对应环境变量
--jp-token <TOKEN>	Joplin API Token	JOPLIN_TOKEN
--jp-host <HOST>	Joplin API 主机地址	JOPLIN_HOST
--jp-port <PORT>	Joplin API 端口	JOPLIN_PORT

配置优先级：命令行参数 > 环境变量

使用示例

# 使用命令行参数配置 Joplin 连接
./joplin-mcp --jp-token "your_token" --jp-host "localhost" --jp-port 41184

# 命令行参数优先于环境变量
JOPLIN_TOKEN="env_token" ./joplin-mcp --jp-token "cli_token"  # 使用 cli_token

# HTTP 模式下同时配置 Joplin 连接和 HTTP 服务器
./joplin-mcp --http --host 127.0.0.1 --port 8080 --jp-token "your_token"

配置 Claude Desktop

stdio 模式（推荐）

在 Claude Desktop 配置中添加：

{
  "mcpServers": {
    "joplin": {
      "command": "path/to/joplin-mcp/target/release/joplin-mcp",
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

Windows 配置示例：

{
  "mcpServers": {
    "joplin": {
      "command": "D:\\projects\\joplin-mcp-rust\\target\\release\\joplin-mcp.exe",
      "env": {
        "JOPLIN_TOKEN": "your_token_here",
        "JOPLIN_HOST": "localhost",
        "JOPLIN_PORT": "41184"
      }
    }
  }
}

HTTP 模式

启动服务器：

./joplin-mcp --http --port 3000

客户端通过 HTTP 连接到 http://localhost:3000/mcp。

工具列表

笔记工具

工具名	描述
create_note	创建新笔记
get_note	获取单个笔记详情
update_note_title	仅更新笔记标题
update_note_body	仅更新笔记正文
append_to_note	追加内容到笔记末尾
prepend_to_note	在笔记开头添加内容
replace_in_note	替换笔记中的文本
move_note	移动笔记到指定笔记本
delete_note	删除笔记（支持永久删除）
list_notes	获取笔记列表
copy_note	复制笔记到指定笔记本
restore_note	从回收站恢复笔记
list_recent_notes	获取最近更新的笔记
clip_webpage	剪藏网页为笔记
paste_image_note	创建带图片的笔记

待办事项工具

工具名	描述
create_todo	创建待办事项
complete_todo	标记待办为已完成
uncomplete_todo	取消完成待办
list_todos	获取待办列表
set_todo_due	设置待办截止时间
clear_todo_due	清除待办截止时间

笔记本工具

工具名	描述
create_folder	创建笔记本
get_folder	获取单个笔记本详情
rename_folder	重命名笔记本
move_folder	移动笔记本
delete_folder	删除笔记本（支持永久删除）
list_folders	获取笔记本列表（支持 as_tree 参数返回树形结构）
get_folder_tree	获取笔记本树形结构（可选指定父节点获取子树）
get_folder_notes	获取笔记本内的笔记列表
set_folder_icon	设置笔记本图标

标签工具

工具名	描述
create_tag	创建标签
get_tag	获取单个标签详情
rename_tag	重命名标签
delete_tag	删除标签
list_tags	获取所有标签
add_tag_to_note	为笔记添加标签
remove_tag_from_note	从笔记移除标签
get_note_tags	获取笔记的所有标签
get_tag_notes	获取具有某标签的所有笔记
merge_tags	合并多个标签到目标标签
set_note_tags	设置笔记的标签（替换现有标签）

资源工具

工具名	描述
upload_resource	上传附件
get_resource	获取资源详情
get_resource_file	下载资源文件
get_resource_notes	获取与资源关联的笔记
delete_resource	删除资源
list_resources	获取资源列表
attach_to_note	将资源关联到笔记

搜索工具

工具名	描述
search_notes	搜索笔记
search_folders	搜索笔记本
search_tags	搜索标签

环境变量

变量名	描述	默认值
JOPLIN_TOKEN	Joplin API Token（必需）	-
JOPLIN_HOST	Joplin API 主机	localhost
JOPLIN_PORT	Joplin API 端口	41184

配置优先级：命令行参数 > 环境变量 > 默认值

Token 校验：程序启动时会检查 Token 是否有效。如果 Token 为空或等于示例值 your_api_token_here，程序会报错并退出，提示需要配置正确的 Token。

技术栈

• Rust: 2024 edition
• rmcp: 官方 MCP Rust SDK
• tokio: 异步运行时
• reqwest: HTTP 客户端
• serde: 序列化/反序列化
• clap: 命令行参数解析
• axum: HTTP 服务器（用于 HTTP 传输模式）

开发

# 调试模式运行（stdio）
cargo run

# HTTP 模式运行
cargo run -- --http

# 发布模式编译
cargo build --release

# 运行测试
cargo test

注意事项

1. DELETE 请求处理: Joplin API 的 DELETE 请求成功时返回空 JSON 响应，这不属于异常情况
2. 端口范围: Joplin Web Clipper 使用端口 41184-41194，默认使用 41184
3. Token 安全: 不要将 Token 提交到版本控制系统
4. 传输模式选择:
   • stdio 模式适用于本地 MCP 客户端（如 Claude Desktop）
   • HTTP 模式适用于远程访问或需要 HTTP API 的场景

License

MIT