运动-mcp-服务器

Name: 运动-mcp-服务器
Author: christopher-czaban

作者：christopher-czaban6 星标更新：2025-06-10

安装使用来源：spider==github.com

项目介绍

Motion MCP Server

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

动机

创建这个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）或默认简化。

总体目标是在尊重AI助手操作约束的同时，从您的Motion工作区传递丰富而有信息量的数据。这使得交互更加流畅、快速，并专注于真正影响您工作流程的信息。

关于Motion任务管理

Motion（https://www.usemotion.com/）是一个由AI驱动的平台，旨在统一和自动化任务管理、项目规划和日历安排。与本MCP服务器相关的关键方面包括：

AI任务及日历规划： Motion利用AI自动将任务安排到您的日历上，考虑优先级、截止日期、依赖关系和可用时间。它会根据新事项的出现或计划的变化动态调整您的日程。
智能优先级： 该平台帮助识别并专注于最紧急和重要的任务，通过主动标记有风险的项目来预防错过截止日期。
统一的工作空间： 它整合了项目、任务和日历，通常与其他工具（如电子邮件和消息应用）集成，以集中您的工作。

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

设置

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

克隆仓库：

git clone <your_repository_url_here> # 替换为实际的URL
cd motion_mcp_server

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）运行服务器，您将遇到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版本。
```
# 示例使用nvm如果Claude Desktop使用Node v18.19.0
nvm install 18.19.0
nvm use 18.19.0

# 示例使用nvm如果Cursor是目标客户端（并且需要v21.1.0）
nvm install 21.1.0
nvm use 21.1.0
```
  - 如果您不知道客户端的Node.js版本，Node.js LTS版本（例如v18.x，v20.x）通常是广泛兼容的好选择。然而，对于这个特定的服务器和客户端组合，瞄准已知兼容的版本是最好的。
安装依赖项： 在您的终端使用正确的Node.js版本后，安装依赖项：
```
npm install
```
这一步安装并针对您的活动Node.js版本编译better-sqlite3。 重要： 如果您后来为了其他项目在本地切换Node.js版本，您可能需要重新构建better-sqlite3以便此项目再次与MCP客户端一起工作。您可以通过运行npm rebuild better-sqlite3 --update-binary或删除node_modules并再次运行npm install（同时使用正确的Node.js版本）来完成此操作。
配置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密钥。
启动服务器： 服务器通常会在您调用其中一个工具时由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 UI）与您的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），您可以在浏览器中打开。在那里，您可以选择您的“motion”服务器，查看其可用工具，并进行调用来测试其响应和行为，包括速率限制。
使用Inspector的重要注意事项：
- 确保在运行npm install（用于better-sqlite3）时活跃的Node.js版本与MCP Inspector启动服务器时使用的版本相同。如果MCP Inspector使用不同的系统Node.js，您可能会遇到NODE_MODULE_VERSION不匹配的问题。您通常可以在启动日志中看到Inspector用于启动您的服务器的命令。
- MOTION_API_KEY必须正确设置在claude_desktop_config.json中服务器定义的env部分，以便Inspector将其传递给您的服务器。

与Claude Desktop的使用

要将此Motion MCP服务器与Claude Desktop一起使用：

找到您的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

编辑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"  // <-- 重要：更改此路径
      ],
      "env": {
        "MOTION_API_KEY": "YOUR_MOTION_API_KEY_HERE" // <-- 重要：更改此密钥
      }
    }
  }
}

重启Claude Desktop。 保存配置文件后，您必须完全退出并重新启动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通信。

使用uv安装mcp-proxy：

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

验证安装并定位二进制文件： 对于不太技术的用户，可以使用以下命令查找安装路径：
```
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"替换为您的实际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客户端

一旦代理服务器运行，根据您的客户端支持的连接类型进行配置：

对于流式HTTP连接

在客户端的MCP配置文件中添加以下配置：

{
  "mcpServers": {
    "motion-mcp": {
      "type": "mcp",
      "url": "http://localhost:8080/mcp",
      "note": "通过HTTP代理的Motion MCP服务器"
    }
  }
}

对于SSE（服务器发送事件）连接

在客户端的MCP配置文件中添加以下配置：

{
  "mcpServers": {
    "motion-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "note": "通过SSE代理的Motion MCP服务器"
    }
  }
}

使用MCP Inspector测试

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

创建一个测试配置文件（例如，mcp-test-config.json），其中包含上述配置之一。

运行Inspector：

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

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

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

重要注意事项

保持代理运行： mcp-proxy服务器必须在您的客户端使用Motion MCP服务器期间持续运行。如果停止代理，您的客户端将失去与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端点的调用。
阻止会超过12次调用/3分钟限制的调用。
当调用被阻止时，提供带有等待时间的明确反馈。
使用本地SQLite数据库（.data/motion_api_ratelimit.sqlite）跨服务器重启持久保存速率限制状态。

理解速率限制错误

当您使用此MCP服务器与AI助手（如Claude Desktop或Cursor