Joplin MCP Rust

Joplin MCP Server

基于 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

命令行参数

传输模式参数

Joplin 连接参数

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

使用示例

# 使用命令行参数配置 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。

工具列表

笔记工具

待办事项工具

笔记本工具

标签工具

资源工具

搜索工具

环境变量

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

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