Joplin MCP 服务器

关键词

JoplinnotebooksnotesintegrationAI-assisted

使用说明

  • 项目简介
    • 本仓库实现了一个基于 MCP（Model Context Protocol）的服务器端，用于将 Joplin 的笔记、本子簿等资源暴露给大语言模型（LLM）客户端。服务器提供资源、工具、提示等能力，支持多种传输模式（标准输入输出、HTTP 流）。通过实现的工具（如 list_notebooks、read_notebook、read_note、search_notes、create_note、delete_note 等），LLM 可以与 Joplin 数据进行交互和操作。
  • 主要功能点
    • MCP 兼容接口：实现 MCP 服务端核心能力，处理 MCP 的请求/响应格式，及工具调用等。
    • 资源管理：通过笔记本/笔记等资源的读取、列举等操作，向客户端提供数据访问能力。
    • 工具注册与执行：公开多种工具（创建、读取、编辑、删除笔记/笔记本等），供 MCP 客户端进行调用。
    • Prompt/模板支持：提供交互所需的提示与渲染能力，便于 LLM 与 Joplin 的协作。
    • 多传输协议：支持 stdio 与 HTTP 流传输，便于本地开发、云端部署及与前端/LLM 框架对接。
    • 集成与扩展：使用 FastMCP 方案实现 HTTP 流传输，基于 FastMCP 的工具定义和参数校验，确保可扩展性。
  • 安装步骤
    • 直接通过 npx 运行（无需本地安装依赖）：
      • 运行命令：npx joplin-mcp-server --help
    • 如需本地开发环境：
      • 安装依赖并构建（如 pnpm 及相关脚本）
      • 运行服务器：npx joplin-mcp-server
    • 配置环境变量
      • JOPLIN_HOST：Joplin 绑定的主机地址，默认为 127.0.0.1
      • JOPLIN_PORT：Joplin Web Clipper 服务端口，默认为 41184
      • JOPLIN_TOKEN：访问 Joplin 的 API Token
  • 服务器配置
    • MCP 客户端需要配置一个 MCP 服务器条目，包含服务器名称、启动命令及参数等信息。示例（请将 TOKEN、端口等替换为实际值）： { "serverName": "joplin", "command": "npx", "args": ["joplin-mcp-server", "--token", "<TOKEN>", "--port", "41184", "--host", "127.0.0.1"] } 注释说明：
    • serverName：在 MCP 客户端的服务器列表中用于识别该后端的名称。与运行的后端对应的服务标识。
    • command：启动服务器的命令，当前实现支持通过 npx 启动 joplin-mcp-server。
    • args：启动参数，包含 token、端口与主机地址等，用于指定与 Joplin 的连接信息。根据实际部署环境，端口、主机、令牌需替换为真实值。
  • 基本使用方法
    • 启动后端服务器后，LLM 客户端通过 MCP 的标准接口调用工具：
      • 列出笔记本：list_notebooks
      • 查看笔记本内容：read_notebook notebook_id=...
      • 读取笔记内容：read_note note_id=...
      • 搜索笔记：search_notes query="..."
      • 创建笔记/笔记本：create_note/create_folder
      • 编辑/删除等操作：edit_note/edit_folder、delete_note/delete_folder
    • 客户端在发送请求时需要遵循 MCP 的 JSON-RPC 风格，服务端返回相应的 JSON-RPC 响应或错误信息。
    • 如需使用 HTTP 传输，使用端口暴露的 HTTP 端点进行交互；如使用 STDIO，直接在命令行中通过进程间通信调用。

服务器信息

访问项目