运动MCP服务器
与Motion（usemotion.com）任务管理平台集成的生产就绪MCP（模型上下文协议）服务器。该服务器使人工智能助手能够通过Motion的API管理项目和任务，同时在 .claude/motion/ 使用markdown文件的目录。
特性
🎯 核心功能
- 全动态API集成：项目、任务、工作区、用户、评论
- 本地存储：使用YAML frontmatter的基于Markdown的任务文件
- 双向同步：保持本地和远程数据与冲突解决同步
- 速率限制：遵守Motion的API限制（个人12分钟，团队120分钟）
🤖 AI驱动的功能
- 任务丰富：人工智能增强的描述和验收标准
- 目标分解：将高级目标转化为可操作的任务列表
- 工作流程规划：制定全面的项目计划
- 状态报告：自动进度总结
📁 MCP资源
- 项目概述：实时项目状态和指标
- 任务文件：单个任务详细信息作为标记资源
- 文档：可通过MCP访问项目文档
- AI提示：任务规划和报告模板
安装
先决条件
- Node.js 18+和npm
- 带有API键的运动帐户
- Claude Desktop（用于MCP集成）
设置
- 克隆并安装
git clone https://github.com/idxstudios/use-motion-mcp-server.git
cd use-motion-mcp-server
npm install- 配置环境
# Copy example environment file
cp .env.example .env
# Edit .env with your Motion API key
MOTION_API_KEY=your_motion_api_key_here
MOTION_IS_TEAM_ACCOUNT=false # true for team accounts- 构建服务器
# Generate OpenAPI routes first (required for first build)
make openapi
# Full build with OpenAPI generation + TypeScript compilation
make build
# OR for TypeScript compilation only (after OpenAPI generated)
npm run build- 配置Claude桌面
编辑您的 claude_desktop_config.json:
{
"mcpServers": {
"motion": {
"command": "node",
"args": ["/absolute/path/to/motion-mcp-server/dist/server/index.js"],
"env": {
"MOTION_API_KEY": "your-motion-api-key"
}
}
}
}建筑
服务器遵循 域控制器→ 应用程序（命令/查询）→ 服务 基于函数式/反应式编程（FRP）原理的模式：
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│Domain Controllers│───▶│ App Layer │───▶│ Services │
│ (MCP Handlers) │ │ Commands/Queries│ │ Motion/Storage │
└─────────────────┘ └─────────────────┘ └─────────────────┘🗂️ 目录结构
src/
├── api/mcp/v1-routes/ # Generated OpenAPI code
│ ├── models/ # Generated TypeScript interfaces
│ ├── routes/ # Generated controller interfaces
│ └── tools.ts # Generated MCP tool schemas
├── api/mcp/v1-controllers/# Domain controller implementations
│ ├── project-controller.ts
│ ├── task-controller.ts
│ ├── workflow-controller.ts
│ ├── sync-controller.ts
│ ├── context-controller.ts
│ └── docs-controller.ts
├── app/ # Business logic layer
│ ├── motion/ # Motion API commands & queries
│ ├── projects/ # Project commands & queries
│ ├── tasks/ # Task commands & queries
│ ├── workflow/ # Workflow planning
│ ├── sync/ # Synchronization logic
│ ├── context/ # Context management
│ └── docs/ # Documentation generation
├── services/ # External service integrations
│ ├── motion-service.ts # Motion API client
│ ├── storage/ # Local file management
│ └── ai/ # AI enhancements
├── setup/ # Configuration and DI
│ └── dependencies.ts # Dependency injection
└── server/index.ts # MCP server entry point🔧 基于OpenAPI的代码生成
工具和接口由YAML模式生成：
- 在中定义工具
schemas/mcp/v1/mcp-tools.yaml - 中的自定义Handlebars模板
schemas/api-gen/server/ - 生成的代码
src/api/mcp/v1-routes/ - 跑
make openapi再生
可用工具
📋 项目管理
motion.project.list-列出所有分页项目motion.project.create-创建新项目motion.project.bind-将项目绑定到本地存储motion.project.sync-将项目与Motion同步
✅ 任务操作
motion.task.create-创建任务（通过人工智能丰富）motion.task.list-列出和筛选任务motion.task.search-在本地存储中搜索任务motion.task.update-更新任务属性motion.task.complete-将任务标记为已完成
🤖 AI功能
motion.task.enrich-AI增强任务描述motion.task.batch_create-根据目标创建多个任务motion.task.analyze-分析任务复杂性motion.workflow.plan-制定全面的计划
🔄 同步和上下文
motion.sync.all-同步所有绑定项目motion.sync.check-检查同步状态motion.context.save-为AI保存项目上下文motion.context.load-加载项目上下文
📄 文档
motion.docs.create-生成项目文档motion.docs.update-更新现有文档motion.status.report-生成状态报告
🏢 工作空间管理
motion.workspace.list-列出所有可用工作区motion.workspace.set_default-为新项目设置默认工作区motion.workspace.get_settings-获取特定于工作区的设置motion.workspace.update_settings-更新工作区首选项
本地存储结构
服务器在中维护本地上下文 .claude/motion/:
.claude/motion/
├── workspace-settings/
│ ├── default.json # Default workspace configuration
│ └── [workspace-id].json # Workspace-specific settings
└── [project-id]/
├── meta.json # Project metadata
├── tasks/
│ └── [task-id].md # Task files with YAML frontmatter
└── docs/
└── *.md # Project documentation任务文件格式
---
id: task_123
projectId: proj_456
status: In Progress
priority: HIGH
duration: 120
# ... other metadata
---
# Task Title
## Description
Detailed task description...
## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2工作区设置格式
{
"workspaceId": "workspace_123",
"defaultProjectId": "project_456",
"defaultPriority": "MEDIUM",
"defaultDuration": 60,
"aiProvider": "openai"
}发展
🛠️ 构建命令（Make）
make help # Show all available commands
make install # Install dependencies
make build # Build the project
make test # Run tests
make lint # Run linter
make dev # Start development server
make check # Run all quality checks
make docker-build # Build Docker image🔍 测试
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test files
npm test -- --testPathPattern=tasks📊 监控
服务器包括全面的错误处理和日志记录：
- 请求/响应日志记录
- 速率限制监控
- 同步冲突检测
- 验证错误报告
Docker部署
构建并运行
# Build image
make docker-build
# Run container
docker run -it --rm \
-v "${PWD}/.claude:/app/.claude" \
-e MOTION_API_KEY="your-api-key" \
motion-mcp-serverDocker Compose
version: '3.8'
services:
motion-mcp:
build: .
volumes:
- ./.claude:/app/.claude
environment:
- MOTION_API_KEY=${MOTION_API_KEY}
- MOTION_IS_TEAM_ACCOUNT=false配置
环境变量
MOTION_API_KEY= # Required: Your Motion API key
MOTION_IS_TEAM_ACCOUNT= # Rate limit configuration
MOTION_BASE_URL= # Motion API base URL
REQUEST_TIMEOUT= # API request timeout (ms)
CLAUDE_DATA_DIR= # Local storage directory
LOG_LEVEL= # Logging verbosity速率限制
服务器会自动检测帐户类型并应用适当的限制：
- 个人账户：12个请求/分钟
- 团队帐户：120个请求/分钟
故障排除
常见问题
❌ “找不到运动API密钥”
# Check environment variables
echo $MOTION_API_KEY
# Verify .env file
cat .env❌ “项目未绑定到本地”
# First bind the project
# Use motion.project.bind tool in Claude❌ 请求频率超限
# Check if team account flag is correct
MOTION_IS_TEAM_ACCOUNT=true # For team accounts调试模式
# Enable debug logging
export LOG_LEVEL=debug
npm startapi参考
服务器实现所有主要的Motion API端点：
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 运行质量检查：
make check - 提交拉取请求
代码的风格
- 具有严格模式的TypeScript
- 函数式/响应式编程模式
- 不可变的数据结构
- 纯功能，无副作用
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
______________________________________________________________________
内置于❤️ 克劳德生态系统