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)

Project Management (5 tools)

Other Tools (8 tools)

Configuration

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

• GitHub
• Motion API Docs
• MCP Protocol