motion-mcp-server by h3ro-dev - MCP Server

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_PATH is writable

"Task not found"

Verify task ID exists
Check workspace access
Task may be archived

h3ro-dev/motion-mcp-server

motion_list_tasks

motion_get_task

motion_create_task

motion_update_task

motion_delete_task