Motion MCP Server
Connect AI assistants to Motion for task and project management.
Installation
npm install -g @h3ro-dev/motion-mcp-server
Quick Setup
1. Get Motion API Key
Motion → Settings → API & Integrations → Create New API Key
2. Configure
Claude Desktop
{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}
Config location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Cursor
{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}
VS Code (with Continue)
{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}
3. Restart your AI assistant
Features
- ✅ All Motion APIs - Tasks, projects, workspaces, users, comments, recurring tasks, schedules
- 🚦 Smart Rate Limiting - Automatic handling of Motion's 12 req/3min limit
- 💾 Persistent State - SQLite database maintains rate limits across restarts
- 🔍 Clear Errors - Helpful messages for debugging
- 📝 Full TypeScript - Type-safe and reliable
Usage Examples
"List my tasks"
"Create task: Review budget, due Friday, high priority"
"Move task abc123 to Marketing workspace"
"Add comment to task xyz789: Waiting for approval"
"Create recurring task: Daily standup at 9am"
Tools Reference
Task Management (7 tools)
| Tool | Description | Example |
|---|---|---|
motion_list_tasks | List tasks with filters | workspaceId, status, assigneeId |
motion_get_task | Get task details | taskId |
motion_create_task | Create new task | name, workspaceId, dueDate, priority |
motion_update_task | Update task | taskId, status, priority |
motion_delete_task | Delete task | taskId |
motion_move_task | Move to workspace | taskId, workspaceId |
motion_unassign_task | Remove assignee | taskId |
Project Management (5 tools)
| Tool | Description | Example |
|---|---|---|
motion_list_projects | List projects | workspaceId |
motion_get_project | Get project details | projectId |
motion_create_project | Create project | name, workspaceId |
motion_update_project | Update project | projectId, name |
motion_archive_project | Archive project | projectId |
Other Tools (8 tools)
| Tool | Description |
|---|---|
motion_list_workspaces | List all workspaces |
motion_get_workspace | Get workspace details |
motion_list_users | List workspace users |
motion_get_current_user | Get current user |
motion_list_comments | List task comments |
motion_create_comment | Add task comment |
motion_list_recurring_tasks | List recurring tasks |
motion_create_recurring_task | Create recurring task |
motion_delete_recurring_task | Delete recurring task |
motion_list_schedules | List schedules |
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
MOTION_API_KEY | ✅ | - | Your Motion API key |
MOTION_BASE_URL | ❌ | https://api.usemotion.com/v1 | API endpoint |
RATE_LIMIT_WINDOW_MS | ❌ | 180000 | Rate limit window (3 min) |
RATE_LIMIT_MAX_REQUESTS | ❌ | 12 | Max requests per window |
DATABASE_PATH | ❌ | ./motion-rate-limit.db | SQLite database path |
DEBUG | ❌ | false | Enable debug logging |
Development
# Clone
git clone https://github.com/h3ro-dev/motion-mcp-server.git
cd motion-mcp-server
# Install
npm install
# Build
npm run build
# Test
npm test
# Run locally
MOTION_API_KEY=your-key npm start
Troubleshooting
Common Issues
"Invalid API Key"
- Check API key is correct
- Ensure no extra spaces
- Regenerate key if needed
"Rate limit exceeded"
- Server automatically handles this
- Wait time shown in error
- Check
DATABASE_PATHis writable
"Task not found"
- Verify task ID exists
- Check workspace access
- Task may be archived
License
MIT © h3ro-dev