Motion MCP 服务器

一个MCP（模型上下文协议）服务器，使LLMs可以直接访问用于项目、任务、用户等的Motion API。用TypeScript构建，具有强大的验证和整合工具，以保持客户端工具列表简洁。

当前版本： 2.2.0

快速开始（npx）

1. 获取你的Motion API密钥 从 https://app.usemotion.com/settings/api

2. 添加到Claude Desktop - 更新你的 claude_desktop_config.json：

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": ["motionmcp"],
      "env": {
        "MOTION_API_KEY": "your_api_key",
        "MOTION_MCP_TOOLS": "essential"
      }
    }
  }
}

3. 测试服务器 - 或者直接从命令行运行：

MOTION_API_KEY=your_motion_api_key npx motionmcp

提示：npx 运行最新发布的版本。

预览

<a href="sample.png"><img src="sample.png" alt="Motion MCP 服务器预览" width="400" /></a>

点击上面的图片查看全尺寸

功能

• 支持MCP协议，实现无缝LLM集成
• 集成Motion API，支持项目、任务、用户、评论、自定义字段和重复任务
• 整合工具 减少工具数量（最小、基本、全部或自定义）
• 上下文工具：语义搜索和轻量级上下文摘要
• 通过环境变量提供API密钥
• 结构化的JSON日志记录
• TypeScript 具有强类型、验证和健壮的错误处理

前提条件

• Node.js 18或更高版本

工具配置

该服务器支持可配置的工具集，以保持在MCP客户端限制内（约100个工具）。通过 MOTION_MCP_TOOLS 环境变量进行配置：

配置选项

最小（3个工具）

适合仅需要基础功能并希望最大化其他MCP服务器空间的用户。

MOTION_MCP_TOOLS=minimal npx motionmcp

可用工具：

• motion_tasks - 任务操作（创建、列出、获取、更新、删除、移动、取消分配）
• motion_projects - 项目操作（创建、列出、获取）
• motion_workspaces - 工作区管理（列出、获取、设置默认）

基本（7个工具，默认）

平衡配置，带有核心功能、搜索、用户管理和调度。

# 默认 - 不需要配置
npx motionmcp
# 或明确地：
MOTION_MCP_TOOLS=essential npx motionmcp

可用工具：

• 包含最小的所有工具，加上：
• motion_users - 用户操作（列出、当前）
• motion_search - 搜索和上下文工具（内容、上下文、智能）
• motion_comments - 评论管理（列出、创建）
• motion_schedules - 调度操作（列出）

完整（10个工具）

所有整合工具，用于完全访问Motion API。

MOTION_MCP_TOOLS=complete npx motionmcp

可用工具：

• 包含基本的所有工具，加上：
• motion_custom_fields - 自定义字段管理（列出、创建、删除、添加/移除）
• motion_recurring_tasks - 重复任务管理（列出、创建、删除）
• motion_statuses - 状态操作（列出）

自定义

指定你需要的确切工具。

MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npx motionmcp

整合工具

整合工具通过合并相关操作来减少总工具数量：

• motion_projects：单一工具用于核心项目操作

  • 操作：create，list，get
  • 示例：{"operation": "create", "name": "新项目", "workspaceName": "个人"}

• motion_tasks：单一工具用于所有任务操作

  • 操作：create，list，get，update，delete，move，unassign
  • 示例：{"operation": "create", "name": "新任务", "projectName": "我的项目"}

• motion_comments：管理任务评论

  • 操作：list，create
  • 示例：{"operation": "create", "taskId": "task_123", "content": "进展很好！"}

• motion_custom_fields：单一工具用于自定义字段管理

  • 操作：list，create，delete，add_to_project，remove_from_project，add_to_task，remove_from_task
  • 示例：{"operation": "create", "name": "优先级别", "type": "DROPDOWN", "options": ["低", "中", "高"]}

• motion_recurring_tasks：单一工具用于重复任务模板

  • 操作：list，create，delete
  • 示例：{"operation": "create", "name": "每周回顾", "workspaceId": "ws_123", "assigneeId": "user_123", "frequency": {"type": "weekly", "daysOfWeek": [1,3,5] }, "duration": 30 }

提供你的Motion API密钥

Motion MCP服务器支持以下方式提供你的API密钥：

1. 环境变量

MOTION_API_KEY=your-key npx motionmcp

2. .env 文件（当通过npm运行时）

在项目旁边创建一个.env文件，内容如下：

MOTION_API_KEY=your-key

当使用npx时，建议如上所示在shell中导出变量。

工具概述

上下文与搜索

• motion_search — 内容搜索、上下文和智能搜索

项目

• motion_projects — 创建、列出、获取

任务

• motion_tasks — 创建、列出、获取、更新、删除、移动、取消分配

评论、自定义字段、重复

• motion_comments — 列出、创建（任务评论）
• motion_custom_fields — 列出、创建、删除、添加/移除于项目或任务
• motion_recurring_tasks — 列出、创建、删除

工作区、用户、调度、状态

• motion_workspaces — 列出、获取、设置默认
• motion_users — 列出（按工作区），当前
• motion_schedules — 用户调度和时区
• motion_statuses — 可用状态（按工作区）

增强功能

智能默认值与解析

• 工作区和项目的自动检测和模糊匹配
• 智能默认值：如果未提供，则选择“个人”工作区
• 健壮的回退和错误消息

任务创建

支持所有Motion API参数：

• 基础：name，description，workspaceId|workspaceName，projectId|projectName
• 高级：priority，dueDate，duration，labels，assigneeId，autoScheduled

语义搜索

• 通过查询跨搜索，智能范围和优先级提升

调度与工作负载

• 带冲突检测和任务平衡的优先级调度
• 按状态、优先级和项目详细的工作负载分解

工具使用示例

使用整合工具创建任务

Tool: motion_tasks
Args: {
  "operation": "create",
  "name": "完成API集成",
  "workspaceName": "开发",
  "projectName": "Q2发布周期",
  "dueDate": "2025-06-15T09:00:00Z",
  "priority": "HIGH",
  "labels": ["api", "release"]
}

添加任务评论

Tool: motion_comments
Args: {
  "operation": "create",
  "taskId": "task_123",
  "content": "已更新讨论中的API端点"
}

创建自定义字段

Tool: motion_custom_fields
Args: {
  "operation": "create",
  "name": "冲刺",
  "type": "DROPDOWN",
  "options": ["冲刺1", "冲刺2", "冲刺3"],
  "workspaceName": "开发"
}

创建重复任务

Tool: motion_recurring_tasks
Args: {
  "operation": "create",
  "name": "每周团队站会",
  "recurrence": "WEEKLY",
  "projectName": "团队会议",
  "daysOfWeek": ["MONDAY", "WEDNESDAY", "FRIDAY"],
  "duration": 30
}

高级Claude Desktop配置

最小配置（仅3个工具）：

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": ["motionmcp"],
      "env": {
        "MOTION_API_KEY": "your_api_key",
        "MOTION_MCP_TOOLS": "minimal"
      }
    }
  }
}

自定义工具选择：

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": ["motionmcp"],
      "env": {
        "MOTION_API_KEY": "your_api_key",
        "MOTION_MCP_TOOLS": "custom:motion_tasks,motion_projects,motion_search"
      }
    }
  }
}

使用本地工作区（npm）：

{
  "mcpServers": {
    "motion": {
      "command": "npm",
      "args": ["run", "mcp:dev"],
      "cwd": "/绝对路径/到你的/MotionMCP",
      "env": {
        "MOTION_API_KEY": "your_api_key",
        "MOTION_MCP_TOOLS": "essential"
      }
    }
  }
}

更多开发者设置和选项，请参阅 DEVELOPER.md。

调试

• 日志输出到 stderr，格式为JSON
• 检查缺失的键、工作区/项目名称和权限
• 使用 motion_workspaces（列出）和 motion_projects（列出）来验证ID

日志示例

{
  "level": "info",
  "msg": "任务创建成功",
  "method": "createTask",
  "taskId": "task_789",
  "workspace": "开发"
}

许可证

Apache-2.0 许可证

---

更多信息，请参阅完整的 Motion API 文档 或 模型上下文协议文档。