Motion

Manage tasks and projects in Motion using AI assistants.

GitHub

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)
ToolDescriptionExample
motion_list_tasksList tasks with filtersworkspaceId, status, assigneeId
motion_get_taskGet task detailstaskId
motion_create_taskCreate new taskname, workspaceId, dueDate, priority
motion_update_taskUpdate tasktaskId, status, priority
motion_delete_taskDelete tasktaskId
motion_move_taskMove to workspacetaskId, workspaceId
motion_unassign_taskRemove assigneetaskId
Project Management (5 tools)
ToolDescriptionExample
motion_list_projectsList projectsworkspaceId
motion_get_projectGet project detailsprojectId
motion_create_projectCreate projectname, workspaceId
motion_update_projectUpdate projectprojectId, name
motion_archive_projectArchive projectprojectId
Other Tools (8 tools)
ToolDescription
motion_list_workspacesList all workspaces
motion_get_workspaceGet workspace details
motion_list_usersList workspace users
motion_get_current_userGet current user
motion_list_commentsList task comments
motion_create_commentAdd task comment
motion_list_recurring_tasksList recurring tasks
motion_create_recurring_taskCreate recurring task
motion_delete_recurring_taskDelete recurring task
motion_list_schedulesList schedules

Configuration

VariableRequiredDefaultDescription
MOTION_API_KEY✅-Your Motion API key
MOTION_BASE_URL❌https://api.usemotion.com/v1API endpoint
RATE_LIMIT_WINDOW_MS❌180000Rate limit window (3 min)
RATE_LIMIT_MAX_REQUESTS❌12Max requests per window
DATABASE_PATH❌./motion-rate-limit.dbSQLite database path
DEBUG❌falseEnable 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

License

MIT © h3ro-dev

Links

Related Servers