Joplin MCP Go

乔普林MCP服务器

一个Windows系统托盘应用程序，通过模型上下文协议（MCP）公开乔普林笔记，使克劳德等人工智能助手能够阅读、创建、更新和搜索你的乔普林笔记。

🌟 特性

• 🔔 系统托盘集成 -轻量级，在Windows系统托盘中安静运行
• 🤖 MCP协议 -全面实施模型上下文协议2024-11-05
• 📝 完整的乔普林通道 -笔记、笔记本和标签的所有CRUD操作
• 🔍 高级搜索 -利用Joplin强大的搜索语法
• ⚡ 快速高效 -资源使用率最低的原生Go应用程序
• 🔐 安全 -使用Joplin内置的API令牌身份验证
• 🎯 轻松设置 -简单的JSON配置

📋 目录

• 先决条件
• 安装
• 配置
• 用法
• 可用工具
• 与Claude Desktop集成
• API 参考
• 故障排除
• 发展
• 许可证

🔧 先决条件

在开始之前，请确保您已经：

• 达到1.21或更高 - 下载Go
• 乔普林桌面 - 下载乔普林
• Windows操作系统 -Windows 10或更高版本（用于系统托盘支持）

📦 安装

快速开始

从下载预编译的二进制文件 发布页面

从源代码构建

1. 克隆或下载项目：

git clone 
cd joplin-mcp-server

1. 下载依赖关系：

go mod download

1. 构建应用程序：

# Standard build
go build -o joplin-mcp-server.exe

# Or build without console window (recommended)
go build -ldflags="-H windowsgui" -o joplin-mcp-server.exe

生产大楼

对于更小、优化的可执行文件：

go build -ldflags="-H windowsgui -s -w" -o joplin-mcp-server.exe

这将删除调试符号并创建无窗口可执行文件。

⚙️ 配置

第一步：启用Joplin Web Clipper

1. 打开 乔普林桌面
2. 导航至 工具→ 选项→ Web Clipper
3. 启用 “启用Web Clipper服务”
4. 注意 端口号 （通常为41184）
5. 复制 授权令牌

步骤2：创建配置文件

创建一个 config.json 与可执行文件位于同一目录中的文件：

{
  "joplin_port": 41184,
  "joplin_token": "your_token_from_joplin_here",
  "mcp_port": 3000
}

配置选项

配置示例

{
  "joplin_port": 41184,
  "joplin_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6.....",
  "mcp_port": 3000
}

🚀 用法

启动服务器

只需双击 joplin-mcp-server.exe 或从命令行运行：

./joplin-mcp-server.exe

该应用程序将：

1. ✅ 启动并显示在系统托盘中
2. ✅ 在配置的端口上启动MCP服务器（默认值：3000）
3. ✅ 测试与乔普林的连接
4. ✅ 日志状态消息（如果控制台窗口可见）

系统托盘菜单

右键单击托盘图标以访问：

• 状态：正在运行 -当前服务器状态（不可点击）
• 配置 -配置设置（未来功能）
• 退出 -停止服务器并退出

验证连接

测试一切是否正常：

# Test Joplin connection
curl http://localhost:41184/ping?token=YOUR_TOKEN

# Test MCP server
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

🛠️ 可用工具

MCP服务器提供8个与Joplin交互的工具：

1. list_notes

列出所有笔记或按文件夹筛选，并支持分页。

{
  "folder_id": "abc123",  // Optional: filter by folder
  "limit": 50,            // Optional: results per page (max 100)
  "page": 1               // Optional: page number
}

2. get_note

通过ID检索完整的笔记。

{
  "note_id": "def456"     // Required: note ID
}

3. create_note

在Joplin中创建新注释。

{
  "title": "My New Note",           // Required: note title
  "body": "# Hello\n\nContent...",  // Required: markdown content
  "folder_id": "abc123"             // Optional: target folder
}

4. update_note

更新现有笔记的标题或内容。

{
  "note_id": "def456",              // Required: note ID
  "title": "Updated Title",         // Optional: new title
  "body": "Updated content..."      // Optional: new content
}

5. delete_note

删除笔记（默认情况下移动到回收站）。

{
  "note_id": "def456"     // Required: note ID to delete
}

6. search_notes

使用Joplin强大的搜索语法搜索笔记。

{
  "query": "meeting notes",  // Required: search query
  "type": "note"            // Optional: note, folder, or tag
}

搜索示例：

• "notebook:Work urgent" -在特定笔记本中搜索
• "tag:important" -按标签搜索
• "created:20241101" -日期创建的注释
• "todo:1" -查找待办事项

7. list_folders

列出乔普林中的所有笔记本/文件夹。

{}  // No parameters required

8. list_tags

列出乔普林中的所有标签。

{}  // No parameters required

🤝 与Claude Desktop集成

添加到您的Claude Desktop配置文件中：

地点： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "joplin": {
      "url": "http://localhost:3000",
      "transport": "http"
    }
  }
}

重新启动克劳德桌面

添加配置后：

1. 完全退出克劳德桌面
2. 重新启动应用程序
3. Joplin MCP服务器工具现在应该可用了

克劳德互动示例

配置后，您可以要求Claude：

• *“显示工作笔记本中的所有笔记”*
• *“使用今天的议程创建一个名为“会议笔记”的新笔记”*
• *“在我的笔记中搜索第四季度预算的参考”*
• *“用牛奶和鸡蛋更新我的购物清单”*
• *“我在乔普林有什么标签？”*

📚 API 参考

MCP端点

服务器公开一个JSON-RPC端点：

POST http://localhost:3000/
Content-Type: application/json

请求格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      // Tool-specific arguments
    }
  }
}

响应格式

成功：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "... response data ..."
      }
    ]
  }
}

错误：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Error description"
  }
}

MCP方法

🔍 故障排除

服务器无法启动

问题： 应用程序崩溃或未出现在托盘中

解决：

• ✅ 验证 config.json 存在并且是有效的JSON
• ✅ 检查端口3000是否未被其他应用程序使用
• ✅ 确保Joplin桌面正在运行
• ✅ 尝试从命令行运行以查看错误消息

无法连接到乔普林

问题： “无法连接到Joplin”错误

解决：

• ✅ 验证Joplin Web Clipper服务是否已启用
• ✅ 检查API令牌是否正确（没有额外的空格）
• ✅ 手动测试： curl http://localhost:41184/ping?token=YOUR_TOKEN
• ✅ 如果41184正在使用中，请尝试其他端口

工具返回错误

问题： MCP工具出现故障或返回意外数据

解决：

• ✅ 验证笔记/文件夹ID是否正确（32个字符的十六进制字符串）
• ✅ 检查乔普林数据库是否损坏
• ✅ 确保您拥有最新版本的Joplin
• ✅ 查看控制台日志以获取详细的错误消息

Claude Desktop找不到服务器

问题： 工具未出现在Claude Desktop中

解决：

• ✅ 验证路径 claude_desktop_config.json 是正确的
• ✅ 使用绝对路径（例如。， C:\\Users\\...)
• ✅ 完全重新启动克劳德桌面
• ✅ 检查服务器是否正在系统托盘中运行

权限问题

问题： 拒绝访问或文件错误

解决：

• ✅ 以管理员身份运行（右键单击→ 以管理员身份运行）
• ✅ 检查防病毒软件没有阻止应用程序
• ✅ 确保config.json与可执行文件位于同一目录中

💻 发展

项目结构

joplin-mcp-server/
├── main.go              # Main application code
├── go.mod               # Go module definition
├── app.ico              # app icon
├── config.json          # Configuration file (user-created)
├── README.md            # This file
└── joplin-mcp-server.exe # Compiled executable

关键组件

乔普林客户 -Joplin REST API的HTTP客户端

• 使用令牌处理身份验证
• 发出HTTP请求（GET、POST、PUT、DELETE）
• 解析JSON响应

MCP服务器 -模型上下文协议服务器

• 实现JSON-RPC 2.0
• 处理MCP协议方法
• 将工具调用路由到Joplin客户端

系统托盘 -Windows集成

• 用途 getlantern/systray 图书馆
• 提供状态菜单
• 在后台运行

添加新工具

要添加新的Joplin工具，请执行以下操作：

1. 在中添加工具定义 tools/list 响应
2. 添加案例 executeTool switch语句
3. 实现Joplin API调用
4. 使用MCP客户端进行测试

从源头构建

# Install dependencies
go mod tidy

# Build for development
go build -o joplin-mcp-server.exe

# Build for production
go build -ldflags="-H windowsgui -s -w" -o joplin-mcp-server.exe

# Cross-compile for Linux (experimental)
GOOS=linux GOARCH=amd64 go build -o joplin-mcp-server

依赖项

• github.com/getlantern/systray -系统托盘支架
• Go标准库（net/http、encoding/json等）

🗺️ 路线图

计划的未来增强功能：

• \[\]配置对话框UI
• \[\]自动检测乔普林端口
• \[\]支持附件/资源
• \[\]跨平台支持（Linux、macOS）
• \[\]WebSocket传输选项
• \[\]更好的错误消息和日志记录

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

贡献领域

• 🐛 错误修复
• 📝 文档改进
• ✨ 新功能
• 🧪 测试覆盖率

📄 许可证

该项目根据MIT许可证获得许可。详见下文：

MIT License

Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🔗 资源

• 乔普林官方网站
• Joplin REST API文档
• 模型上下文协议规范
• Go 编程语言
• Systray库

📞 支持

如果您遇到问题：

1. 检查 故障排除 章节
2. 审查 已解决的问题
3. 打开A 新问题 与：

- 您的Go版本 - 你的乔普林版本 - Windows版本 - 错误消息/日志 - 重现步骤

🙏 致谢

• Joplin团队擅长记笔记
• 模型上下文协议规范的拟人化
• 去社区寻找令人惊叹的库和工具

______________________________________________________________________

由以下材料制成❤️ 乔普林和人工智能助理社区

*星⭐ 如果你觉得这个仓库有用的话！*