AI导哈

任务管理MCP服务器

一个开源的MCP服务器，使AI助手能够通过Motion API进行智能任务和项目管理。

  • by christopher-czaban
  • TypeScript
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 christopher-czaban/motion-mcp-server

使用说明

运动MCP服务器

开源MCP服务器，使人工智能助手能够与Motion API交互，实现智能任务和项目管理。

目录

动机

创建此Motion MCP服务器的主要动机是将强大的AI助手（如Claude Desktop、Cursor等）与Motion强大的任务和项目管理功能无缝集成(https://www.usemotion.com/).通过MCP工具公开Motion的API，用户可以通过与首选的人工智能助手交流，使用自然语言管理他们的任务、项目和时间表。这弥合了对话式人工智能和结构化个人/团队生产力之间的差距，旨在实现更直观、更高效的工作流程。

特性

  • 用于各种运动API端点（项目、任务、用户等）的MCP工具。
  • 自动速率限制，以防止超过动态API配额（每3分钟12次呼叫）。
  • 使用本地SQLite数据库在服务器重启时进行速率限制的持久状态。

提高人工智能效率的智能数据检索

此MCP服务器在设计时考虑了人工智能助手，特别是在交换数据的数量和相关性方面。与API交互通常会导致冗长的响应，使AI的上下文窗口充斥着可能不会立即有用的信息。为了解决这个问题，服务器采用了几种提高令牌效率的策略：

  • 合理违约： 对于大多数检索数据的工具（如获取任务或项目），服务器会返回一组精心策划的默认字段。选择这些默认值是为了一目了然地提供最常用的信息，确保您在没有不必要的混乱的情况下获得关键细节。

  • 用户控制的特异性： 虽然默认设置很有帮助，但您始终处于控制之中。如果您需要更多（或不同的）信息，您可以指示您的人工智能助手从Motion API请求特定字段。这可以从要求一些额外的细节到要求特定项目的完整数据集。这种灵活性确保您在需要时得到所需的东西。

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

    • 当你询问任务分配者的列表时，默认情况下，为了简洁起见，它可能只返回他们的名字。
    • 日期通常会自动格式化为一致的、人类可读的格式 YYYY-MM-DD 格式。
    • 嵌套对象内的信息（如项目经理的详细信息）可以直接访问（例如。， manager.name)或默认简化。

总体目标是取得平衡：从您的Motion工作区提供丰富、信息丰富的数据，同时尊重人工智能助手的操作限制。这使得交互更顺畅、更快，并且更专注于对您的工作流程真正重要的信息。

关于运动任务管理

运动(https://www.usemotion.com/)是一个基于人工智能的平台，旨在统一和自动化任务管理、项目规划和日历调度。与此MCP服务器相关的关键方面包括：

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

此MCP服务器允许AI助手利用这些功能，使用户能够通过自然语言与他们的运动任务和日程进行交互。

设置

按照以下步骤设置和运行Motion MCP服务器：

  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.

    • 问题： 如果安装依赖项(npm install)使用一个Node.js版本（例如v21.x， NODE_MODULE_VERSION 120)然后尝试使用使用不同的、与ABI不兼容的Node.js版本的MCP客户端运行服务器（例如，Claude Desktop经常使用Node.js v18.x， NODE_MODULE_VERSION 108)，你会遇到 ERR_DLOPEN_FAILED 错误。错误消息通常会声明该模块“是针对不同的Node.js版本编译的”。
    • 解决方案：
      • 确定MCP客户端使用的Node.js版本。 例如，Claude Desktop日志通常显示它使用的Node.js版本（例如，“Node.js v18.19.0”）。对于 光标，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 跑步 npm install 再次使用正确的Node.js版本。

  4. 配置API密钥： 服务器希望Motion API密钥作为名为的环境变量可用 MOTION_API_KEY.

    • 对于MCP客户端（如Claude Desktop、Cursor）： 在客户端的MCP服务器设置中配置此设置。请参阅“使用Claude Desktop”部分以获取示例。
    • 对于本地shell执行（测试/开发）：
      export MOTION_API_KEY="your_motion_api_key_here"
      替换 "your_motion_api_key_here" 使用实际的运动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检查器进行调试

    这 @modelcontextprotocol/inspector 是本地测试和调试MCP服务器的宝贵工具。它允许您查看客户端（如Inspector的web UI）和MCP服务器之间的通信。

    1. 确保在MCP客户端配置文件中配置了服务器（推荐）： 使用检查器的最简单方法是将其指向现有的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 flag告诉Inspector从该配置文件中专门代理名为“motion”的服务器。

    2. 在没有完整配置文件的情况下使用MCP检查器（替代方案）： 虽然可能，但它更复杂，因为您需要通过命令行参数直接向检查器提供所有服务器参数（命令、参数、环境变量）。使用 --config 和 --server 如果您已经为像Claude Desktop这样的客户端定义了服务器，那么上面显示的标志会更简单。

    3. 访问检查器： 一旦启动，MCP检查器将输出一个URL（通常 http://127.0.0.1:6274)您可以在网络浏览器中打开。从那里，您可以选择您的“运动”服务器，查看其可用工具，并调用以测试其响应和行为，包括速率限制。

    检查员使用须知：

    • 确保运行时终端中的Node.js版本处于活动状态 npm install （为 better-sqlite3)MCP Inspector将用于启动您的服务器。如果MCP Inspector使用不同的Node.js系统，您可能会遇到 NODE_MODULE_VERSION 不匹配。您经常可以在启动日志中看到Inspector用于启动服务器的命令。
    • 这 MOTION_API_KEY 必须正确设置 env 服务器定义中的部分 claude_desktop_config.json 以便检查员将其传递给您的服务器。

使用Claude Desktop

要将此Motion MCP服务器与Claude Desktop一起使用，请执行以下操作：

  1. 找到您的Claude Desktop配置文件。 这通常可以在以下位置找到：

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

  2. 编辑 claude_desktop_config.json 文件。 添加或更新 mcpServers 部分将包括“运动”服务器的条目。 重要提示：

    • 替换 "/path/to/your/motion_mcp_server/main.ts" 随着 绝对路径 到 main.ts 文件在 您的克隆存储库.
    • 替换 "YOUR_MOTION_API_KEY_HERE" 使用实际的运动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应该能够调用Motion工具（例如“Motion get_tasks”）。

通过MCP代理与SSE/HTTP客户端一起使用

一些AI客户端和应用程序只支持服务器发送事件（SSE）或可流式传输的HTTP连接，而不支持标准的MCP stdio协议。对于这些客户，您可以使用 mcp-proxy 服务器桥接HTTP/SSE客户端和此Motion MCP服务器之间的连接。

先决条件

在继续之前，请确保您已完成基本 设置 此Motion MCP服务器的步骤，包括：

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

安装MCP代理

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

  1. 使用uv安装mcp代理：

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

  2. 验证安装并找到二进制文件： 对于技术水平较低的用户，您可以使用以下命令找到安装路径：

    which mcp-proxy

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

启动MCP代理服务器

使用您的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" 使用实际的运动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（服务器发送事件）连接

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

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

MCP检验员测试

您可以使用MCP检查器工具测试您的代理设置：

  1. 创建测试配置文件 （例如。， mcp-test-config.json)具有上述配置之一。

  2. 运行检查器：

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

    （使用 --server motion-sse 如果您正在测试SSE配置）

  3. 访问检查员： 打开检查器提供的URL（通常 http://127.0.0.1:6274)在您的web浏览器中，通过代理测试Motion工具。

重要提示

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

  • 端口冲突： 如果端口8080已经在使用中。， --port 8081)并相应地更新您的客户端配置URL。

  • 速率限制： 使用代理时，同样的速率限制规则也适用。无论连接方法如何，Motion API都会强制执行每3分钟12次调用的限制。

  • 安全： 代理服务器在本地运行并公开HTTP端点。确保您的防火墙设置适合您的安全要求。

将AI连接到运动的其他方法

值得注意的是，Zapier还为Motion提供了MCP集成，可以在 https://zapier.com/mcp/motion这允许用户通过Zapier平台将AI助手连接到Motion，利用他们广泛的现有应用程序连接。

主要区别和注意事项：

  • Zapier平台： 依赖于Zapier的基础设施，并可能涉及其订阅层，以便在超出某些免费限制的情况下使用（Zapier表示，他们的MCP集成对个人免费，但不超过某些费率限制，如40个电话/小时或300个电话/月）。
  • 此服务器（开源）： 此存储库中提供的服务器是开源和自托管的。这意味着：
    • 无供应商锁定： 您可以完全控制代码和部署。
    • 成本： 免费使用，费用仅与您自己的主机（如果有）和运动API使用本身有关。
    • 定制： 您可以根据需要直接修改和扩展此服务器的功能。

据我们所知，除了Zapier的产品外，该存储库还提供了一个独特的开源MCP服务器，专门用于与Motion API直接集成。

速率限制

此服务器为Motion API实现自动速率限制，以防止超过API的速率限制 每3分钟滚动窗口12次通话速率限制器：

  • 跟踪对运动API终结点进行的所有API调用。
  • 阻止超过12个呼叫/3分钟限制的呼叫。
  • 当呼叫被阻止时，提供关于等待时间的明确反馈。
  • 使用本地SQLite数据库在服务器重启时保持速率限制状态(.data/motion_api_ratelimit.sqlite).

了解速率限制错误

当您将此MCP服务器与人工智能助手（如Claude Desktop或Cursor）一起使用时，如果尝试调用Motion API被服务器的速率限制器阻止，人工智能助手将收到一条结构化错误消息。作为与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. 通知您： 人工智能助手应通知您（用户）由于临时速率限制，操作无法完成，并将提到所需的等待时间（例如，“我现在无法完成，因为已达到运动API速率限制。请在X秒后重试。”）。
  2. AI不会立即重试： 助手本身不应立即重试该命令。它应该尊重 waitTimeSeconds.
  3. 为您提供的指导： 根据AI的消息，在要求AI助手尝试相同或另一个与运动相关的命令之前，您应该至少等待指定的时间。

该机制确保服务器遵守Motion API的限制，同时通过人工智能助手向您提供清晰的反馈，从而获得更流畅的体验。

致谢和确认

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

  • SpecToMCP 是一个非常有用的工具，可以根据OpenAPI（Swagger）规范生成基础模型上下文协议服务器。这大大加快了该项目的初始开发，提供了一个强大的起点，然后进行了迭代。
  • 您可以在此处找到SpecToMCP并了解更多信息： https://spectomcp.updab.com/

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

故障排除

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

    • 解决方案： 仔细遵循 步骤2 在 设置 之前对齐Node.js版本的部分 npm install。你可能需要跑步 npm rebuild better-sqlite3 --update-binary 或删除 node_modules 和 package-lock.json 然后跑 npm install 再次启用正确的Node.js版本。

  • 找不到API密钥/无效： 确保 MOTION_API_KEY 环境变量设置正确（按照安装程序或MCP客户端配置中的步骤4），密钥本身有效且未被撤销。

  • 数据库问题(.data/motion_api_ratelimit.sqlite): SQLite数据库存储在 .data/ 项目中的目录。此目录和文件应自动创建。

    • 如果您怀疑存在损坏（例如，在确认Node.js版本正确后，与数据库相关的持续错误），可以尝试删除 motion_api_ratelimit.sqlite 文件。服务器将在下次启动时尝试重新创建它。 警告：这将重置速率限制历史记录，如果您之前受到速率限制，则可能会出现突发呼叫。

  • MCP客户端配置中的路径问题： 仔细检查路径 main.ts 在MCP客户端的配置中（例如。， claude_desktop_config.json)是正确的吗 绝对路径 为您的系统。

贡献

欢迎提出问题和功能请求！请通过此存储库的GitHub问题跟踪器提交它们。如果你想贡献代码，请先打开一个问题来讨论拟议的更改。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP