Motion MCP Server

Motion MCP 服务

一个开源 MCP 服务，可让 AI 助手与 Motion API 交互，实现智能任务和项目管理。

目录

• 动机
• 功能
• 面向 AI 效率的智能数据检索
• 关于 Motion 任务管理
• 设置
• 与 Claude Desktop 搭配使用
• 通过 MCP Proxy 与 SSE/HTTP 客户端搭配使用
• 连接 AI 与 Motion 的其他方式
• 速率限制
• 了解速率限制错误
• 鸣谢
• 故障排除
• 参与贡献
• 许可证

动机

创建此 Motion MCP 服务的主要目的是将强大的 AI 助手（如 Claude Desktop、Cursor 等）与 Motion（https://www.usemotion.com/）强大的任务和项目管理功能无缝集成。通过 MCP 工具开放 Motion API，用户可以用自然语言与自己偏好的 AI 助手交流，从而管理任务、项目和日程。这在对话式 AI 与结构化的个人／团队效率管理之间搭起了桥梁，旨在打造更直观、高效的工作流。

功能

• 为 Motion API 的各类端点提供 MCP 工具（项目、任务、用户等）。
• 自动进行速率限制，避免超出 Motion API 配额（每 3 分钟 12 次调用）。
• 使用本地 SQLite 数据库持久化速率限制状态，以便在服务重启后保留状态。

面向 AI 效率的智能数据检索

此 MCP 服务专为 AI 助手设计，尤其考虑了数据交换的数量和相关性。与 API 交互时，响应往往冗长，可能会用当前并非特别有用的信息占满 AI 的上下文窗口。为此，服务采用了多种策略来提高令牌效率：

• 合理的默认值： 对于大多数检索数据的工具（例如获取任务或项目），服务会返回经过筛选的默认字段。这些默认值旨在一目了然地呈现最常用的信息，让你无需面对冗余内容，也能获取关键详情。

• 由用户控制具体内容： 默认值虽然实用，但你始终可以掌控所需信息。如果需要更多或不同的信息，可以指示 AI 助手向 Motion API 请求指定字段。你既可以要求获取少量额外详情，也可以请求特定项目的完整数据集。这种灵活性可确保你在需要时准确获取所需信息。

• 复杂数据的智能处理： 服务会对复杂数据结构（如项目列表或嵌套信息）进行智能处理。例如：

  • 当你请求任务负责人列表时，默认情况下可能只返回姓名，以简化内容。
  • 日期通常会自动格式化为统一、易读的 YYYY-MM-DD 格式。
  • 可以直接访问嵌套对象中的信息（如项目经理的详情）（例如 manager.name），也可以使用默认的简化形式。

总体目标是在两者之间取得平衡：从 Motion 工作区提供丰富、详尽的数据，同时兼顾 AI 助手的运行限制。这样可以让交互更顺畅、更快捷，并更聚焦于对工作流真正重要的信息。

关于 Motion 任务管理

Motion（https://www.usemotion.com/）是一个由 AI 驱动的平台，旨在整合并自动化任务管理、项目规划和日历安排。与此 MCP 服务相关的主要功能包括：

• AI 任务与日历规划： Motion 使用 AI 自动将任务安排到日历中，同时考虑优先级、截止日期、依赖关系和可用时间。随着新事项出现或计划发生变化，它会动态调整日程。
• 智能优先级排序： 该平台可帮助识别并专注于最紧急、最重要的任务，旨在通过主动标记存在风险的事项来避免错过截止日期。
• 统一工作区： 它整合了项目、任务和日历，通常还会与电子邮件和消息应用等其他工具集成，以集中管理工作。

此 MCP 服务允许 AI 助手利用这些功能，让用户通过自然语言与 Motion 任务和日程进行交互。

设置

按照以下步骤设置并运行 Motion MCP Server：

1. 克隆仓库：

   git clone <your_repository_url_here> # Replace with the actual URL
   cd motion_mcp_server
   

2. Node.js 版本（对 better-sqlite3 至关重要）： 此项目使用 better-sqlite3，这是一个原生 Node.js 模块。原生模块会针对特定的 Node.js 应用程序二进制接口（ABI）版本进行编译，该版本由 NODE_MODULE_VERSION 标识。

   • **问题：**如果你使用一个 Node.js 版本（例如 v21.x，NODE_MODULE_VERSION 120）安装依赖项（npm install），然后尝试通过使用另一个 ABI 不兼容的 Node.js 版本（例如，Claude Desktop 通常使用 Node.js v18.x，NODE_MODULE_VERSION 108）的 MCP 客户端运行服务，就会遇到 ERR_DLOPEN_FAILED 错误。错误消息通常会指出该模块“是针对不同的 Node.js 版本编译的”。
   • 解决方案：
     • **确定 MCP 客户端使用的 Node.js 版本。**例如，Claude Desktop 日志通常会显示其使用的 Node.js 版本（例如，“Node.js v18.19.0”）。对于 Cursor，经测试，Node.js v21.1.0 可与此 MCP 服务正常配合使用（截至 2024 年 5 月）。
     • 使用 Node.js 版本管理器（如 nvm 或 nvs），在继续下一步之前，先在本地终端安装并切换到相同的 Node.js 版本。

       # Example using nvm if Claude Desktop uses Node v18.19.0
       nvm install 18.19.0
       nvm use 18.19.0
       
       # Example using nvm if Cursor is the target client (and v21.1.0 is desired)
       nvm install 21.1.0
       nvm use 21.1.0
       

     • 如果你不知道客户端使用的 Node.js 版本，Node.js LTS 版本（例如 v18.x、v20.x）通常是兼容性更广的不错选择。不过，对于此特定的服务和客户端组合，最好使用已知兼容的版本。

3. 安装依赖项： 终端使用正确的 Node.js 版本后，安装依赖项：

   npm install
   

   此步骤会安装 better-sqlite3，并针对当前使用的 Node.js 版本进行编译。 **重要：**如果之后为了其他项目在本地切换了 Node.js 版本，你可能需要重新构建 better-sqlite3，才能让此项目再次与 MCP 客户端配合使用。你可以运行 npm rebuild better-sqlite3 --update-binary，或者删除 node_modules，然后在使用正确 Node.js 版本时再次运行 npm install。

4. 配置 API 密钥： 服务需要通过名为 MOTION_API_KEY 的环境变量获取 Motion API 密钥。

   • 用于 MCP 客户端（如 Claude Desktop、Cursor）： 在客户端的 MCP 服务设置中进行配置。示例请参见“与 Claude Desktop 配合使用”一节。
   • 用于本地 shell 执行（测试／开发）：

     export MOTION_API_KEY="your_motion_api_key_here"
     

     将 "your_motion_api_key_here" 替换为你的实际 Motion API 密钥。

5. 启动服务： 通常，调用 MCP 客户端的某个工具时，客户端会自动启动服务。

   • 使用 npx tsx 进行本地开发／测试（推荐）： 如果要直接运行服务（例如，配合 MCP Inspector 使用），请确保当前位于项目根目录，并且当前使用的 Node.js 版本与运行 npm install 时使用的版本一致。

     npx tsx main.ts
     

     tsx 是用于直接执行 TypeScript 文件的实用工具。如果你之前没有使用过，可能需要安装它或使用 ts-node。
   • 使用 npm start（如果已配置）： 如果你的 package.json 中有类似 "start": "tsx main.ts" 的启动脚本，可以使用：

     npm start
     

   使用 MCP Inspector 调试

   @modelcontextprotocol/inspector 是一个很实用的工具，可用于在本地测试和调试 MCP 服务。它可以让你查看客户端（如 Inspector 的 Web 界面）与 MCP 服务之间的通信。

   1. 确保在 MCP 客户端配置文件中配置了服务（推荐）： 使用 Inspector 最简单的方法是指定一个现有的 MCP 客户端配置文件，其中已定义 motion 服务（如“与 Claude Desktop 配合使用”一节所述）。例如，使用你的 Claude Desktop 配置：

      npx @modelcontextprotocol/inspector --config "/path/to/your/Claude/claude_desktop_config.json" --server motion
      

      • 将 "/path/to/your/Claude/claude_desktop_config.json" 替换为你的 Claude Desktop 配置文件的实际路径。
      • --server motion 标志会告知 Inspector 从该配置文件中指定代理名为 "motion" 的服务。

   2. 不使用完整配置文件运行 MCP Inspector（替代方法）： 虽然可行，但操作更复杂，因为你需要通过命令行参数将所有服务参数（命令、参数、环境变量）直接提供给 Inspector。如果你已经为 Claude Desktop 等客户端定义了服务，使用上面所示的 --config 和 --server 标志会更简单。

   3. 访问 Inspector： 启动后，MCP Inspector 会输出一个 URL（通常为 http://127.0.0.1:6274），你可以在 Web 浏览器中打开。之后，你可以选择 "motion" 服务，查看可用工具，并调用工具来测试其响应和行为，包括速率限制。

   使用 Inspector 时的重要事项：

   • 确保运行 npm install（用于 better-sqlite3）时终端中使用的 Node.js 版本，与 MCP Inspector 启动服务时使用的版本相同。如果 MCP Inspector 使用了不同的系统 Node.js，可能会遇到 NODE_MODULE_VERSION 不匹配的问题。通常可以在 Inspector 的启动日志中查看它用于启动服务的命令。
   • 必须在 claude_desktop_config.json 中服务定义的 env 部分正确设置 MOTION_API_KEY，这样 Inspector 才能将其传递给服务。

在 Claude Desktop 中使用

如需在 Claude Desktop 中使用此 Motion MCP 服务：

1. 找到 Claude Desktop 配置文件。 通常位于：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 编辑 claude_desktop_config.json 文件。 添加或更新 mcpServers 部分，加入 "motion" 服务的条目。 重要：

   • 将 "/path/to/your/motion_mcp_server/main.ts" 替换为 你克隆的仓库 中 main.ts 文件的绝对路径。
   • 将 "YOUR_MOTION_API_KEY_HERE" 替换为你的实际 Motion API 密钥。

   {
     "mcpServers": {
       "motion": {
         "command": "npx",
         "args": [
           "tsx",
           "/path/to/your/motion_mcp_server/main.ts"  // <-- IMPORTANT: Change this path
         ],
         "env": {
           "MOTION_API_KEY": "YOUR_MOTION_API_KEY_HERE" // <-- IMPORTANT: Change this key
         }
       }
     }
   }
   

3. 重启 Claude Desktop。 保存配置文件后，必须完全退出并重启 Claude Desktop，才能使更改生效。

完成配置并重启后，Claude 应该能够调用 Motion 工具（例如，“motion get_tasks”）。

通过 MCP Proxy 与 SSE/HTTP 客户端配合使用

有些 AI 客户端和应用仅支持 Server-Sent Events（SSE）或可流式传输的 HTTP 连接，而不支持标准的 MCP stdio 协议。对于这些客户端，你可以使用 mcp-proxy 服务，在 HTTP/SSE 客户端与此 Motion MCP 服务之间搭建连接桥梁。

前提条件

继续操作前，请确保已完成此 Motion MCP 服务的基本设置，包括：

• 安装 Node.js 和依赖项
• 配置你的 MOTION_API_KEY

安装 MCP Proxy

mcp-proxy 服务充当桥梁，将 HTTP/SSE 请求转换为与此 Motion 服务进行的 MCP stdio 通信。

1. 使用 uv 安装 mcp-proxy：

   uv tool install git+https://github.com/sparfenyuk/mcp-proxy
   

2. 验证安装并查找二进制文件： 对于不熟悉技术操作的用户，可以使用以下命令查找安装路径：

   which mcp-proxy
   

   这将输出 mcp-proxy 二进制文件的完整路径（例如，/home/user/.local/bin/mcp-proxy）。

启动 MCP Proxy 服务

使用你的 Motion API 密钥以及此服务的 main.ts 文件路径，启动代理服务：

/path/to/mcp-proxy --port 8080 --env MOTION_API_KEY "your_motion_api_key_here" npx tsx /path/to/your/motion_mcp_server/main.ts

需要替换的内容：

• 将 /path/to/mcp-proxy 替换为 which mcp-proxy 命令返回的实际路径
• 将 "your_motion_api_key_here" 替换为你的实际 Motion API 密钥
• 将 /path/to/your/motion_mcp_server/main.ts 替换为此服务的 main.ts 文件的绝对路径

示例：

/home/user/.local/bin/mcp-proxy --port 8080 --env MOTION_API_KEY "mt_abc123xyz789" npx tsx /home/user/projects/motion-mcp-server/main.ts

配置你的 MCP 客户端

代理服务运行后，根据客户端支持的连接类型配置你的 MCP 客户端：

对于可流式传输的 HTTP 连接

将此配置添加到客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "motion-mcp": {
      "type": "mcp",
      "url": "http://localhost:8080/mcp",
      "note": "Motion MCP server via HTTP proxy"
    }
  }
}

对于 SSE（Server-Sent Events）连接

将此配置添加到客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "motion-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "note": "Motion MCP server via SSE proxy"
    }
  }
}

使用 MCP Inspector 进行测试

你可以使用 MCP Inspector 工具测试代理配置：

1. 创建测试配置文件（例如，mcp-test-config.json），内容为上述任一配置。

2. 运行 Inspector：

   npx @modelcontextprotocol/inspector --config /path/to/mcp-test-config.json --server motion-mcp
   

   （如果要测试 SSE 配置，请使用 --server motion-sse）

3. 访问 Inspector： 在 Web 浏览器中打开 Inspector 提供的 URL（通常为 http://127.0.0.1:6274），通过代理测试 Motion 工具。

重要说明

• **保持代理运行：**客户端使用 Motion MCP 服务期间，mcp-proxy 服务必须保持运行。如果停止代理，客户端将失去与 Motion 工具的连接。

• **端口冲突：**如果端口 8080 已被占用，请选择其他端口（例如 --port 8081），并相应更新客户端配置 URL。

• **速率限制：**使用代理时同样适用相同的速率限制规则。Motion API 的 3 分钟内调用 12 次限制无论使用哪种连接方式都会生效。

• **安全性：**代理服务在本地运行，并会公开 HTTP 端点。请确保防火墙设置符合你的安全要求。

将 AI 连接到 Motion 的其他方式

值得一提的是，Zapier 也为 Motion 提供 MCP 集成，可通过 https://zapier.com/mcp/motion 获取。用户可以通过 Zapier 平台将 AI 助手连接到 Motion，并利用其丰富的现有应用连接。

主要区别和注意事项：

• **Zapier 平台：**依赖 Zapier 的基础设施，超出某些免费额度后可能需要订阅其套餐（Zapier 表示，其 MCP 集成对个人用户免费，但设有一定的速率限制，例如每小时 40 次调用或每月 300 次调用）。
• **本服务（开源）：**此代码库提供的服务为开源且可自托管。这意味着：
  • **无供应商锁定：**你可以完全掌控代码和部署。
  • **费用：**免费使用，费用仅涉及你自己的托管（如有）以及 Motion API 本身的使用。
  • **定制：**你可以根据需要直接修改并扩展此服务的功能。

据我们所知，除了 Zapier 提供的方案外，此代码库还提供了一个独特的开源 MCP 服务，专为直接集成 Motion API 而设计。

速率限制

此服务会自动限制 Motion API 的调用，以防超出其滚动 3 分钟窗口内调用 12 次的限制。速率限制器：

• 跟踪对 Motion API 端点发起的所有 API 调用。
• 阻止会超出 3 分钟内调用 12 次限制的请求。
• 请求被阻止时，会提供清晰的反馈并告知等待时间。
• 使用本地 SQLite 数据库（.data/motion_api_ratelimit.sqlite）在服务重启后保留速率限制状态。

了解速率限制错误

当你将此 MCP 服务与 AI 助手（如 Claude Desktop 或 Cursor）搭配使用，并且 Motion API 调用尝试被服务的速率限制器拦截时，AI 助手会收到一条结构化错误消息。作为与 AI 助手互动的用户，你通常会在聊天界面中看到助手转述这条错误。

速率限制错误消息示例（工具调用返回）：

{
  "error": "Rate Limit Exceeded",
  "details": "Motion API rate limit reached. Please wait X seconds before trying again.",
  "waitTimeSeconds": X 
}

以下示例展示了触发速率限制时，这类错误在 AI 助手界面（例如 Claude Desktop）中的显示方式。助手会转述服务的错误，其中包含等待时间：

说明：多次调用 Motion MCP 服务的工具后，速率限制错误在 AI 助手界面中的显示示例。

AI 助手应如何响应：

大多数与 MCP 工具集成的 AI 助手都能够理解这类结构化错误。

1. **通知你：**AI 助手应告知你（用户），由于临时速率限制，此操作无法完成，并说明所需的等待时间（例如：“我现在无法执行此操作，因为 Motion API 已达到速率限制。请在 X 秒后重试。”）。
2. **AI 不应立即重试：**助手本身不应立即重试该命令，而应遵守 waitTimeSeconds。
3. **为你提供指引：**根据 AI 的提示，你应至少等待指定时长，然后再让 AI 助手尝试相同或其他与 Motion 相关的命令。

此机制可确保服务遵守 Motion API 的限制，同时通过 AI 助手向你提供清晰的反馈，从而带来更顺畅的使用体验。

致谢

此 Motion MCP 服务最初使用 Updab AB 的 SpecToMCP 工具搭建。

• SpecToMCP 是一款非常实用的工具，可根据 OpenAPI（Swagger）规范生成基础的模型上下文协议服务。它为本项目提供了可靠的起点，之后我们在此基础上不断迭代，显著加快了项目的初期开发。
• 你可以在此找到 SpecToMCP 并了解更多信息：https://spectomcp.updab.com/

我们感谢 Updab 为开发者社区提供如此宝贵的资源。

故障排除

• ERR_DLOPEN_FAILED / NODE_MODULE_VERSION 版本不匹配： 这是最常见的问题，尤其是在使用 better-sqlite3 时。这意味着用于安装依赖项（并编译 better-sqlite3）的 Node.js 版本，与 MCP 客户端（例如 Claude Desktop）运行服务时使用的 Node.js 版本不同。

  • 解决方案： 请仔细按照 Setup 部分中的 Step 2 操作，在运行 npm install 前确保 Node.js 版本一致。你可能需要运行 npm rebuild better-sqlite3 --update-binary，或者删除 node_modules 和 package-lock.json，然后在启用正确的 Node.js 版本后重新运行 npm install。

• 未找到 / 无效的 API 密钥： 确保已正确设置 MOTION_API_KEY 环境变量（按照 Setup 中的 Step 4 设置，或在 MCP 客户端配置中设置），并且密钥本身有效且未被撤销。

• 数据库问题（.data/motion_api_ratelimit.sqlite）： SQLite 数据库存储在项目中的 .data/ 目录下。该目录和文件应会自动创建。

  • 如果怀疑数据库已损坏（例如，在确认 Node.js 版本正确后，仍持续出现与数据库相关的错误），可以尝试删除 motion_api_ratelimit.sqlite 文件。服务会在下次启动时尝试重新创建该文件。警告：这会重置速率限制历史记录；如果你之前受到速率限制，可能会因此允许短时间内大量调用。

• MCP 客户端配置中的路径问题： 请仔细检查 MCP 客户端配置（例如 claude_desktop_config.json）中 main.ts 的路径是否为系统上的正确绝对路径。

贡献

欢迎提交问题和功能请求！请通过此仓库的 GitHub 问题跟踪器提交。如果你想贡献代码，请先提交问题，讨论拟议的更改。

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。