Motion MCP Server

A Model Context Protocol (MCP) server providing comprehensive access to the Motion task and project management API. Deploy this MCP to help AI assistants like Claude Code manage tasks, projects, and schedules in Motion.

🚀 Quick Deploy

This will deploy your Motion MCP server to a URL like: motion-mcp.<your-account>.workers.dev/sse

Important: After deployment, you must add your MOTION_API_KEY as a secret in your Cloudflare Workers dashboard.

Related MCP server: Motion MCP Server

📋 What This MCP Provides

This MCP server gives AI assistants full access to Motion's API with 25+ specialized tools:

Available Tools

Configuration

• set_api_key - Set your Motion API key for this session (required when using public server)

Workspaces & Users

• list_workspaces - List all workspaces

• list_users - List users in a workspace

• get_my_user - Get current authenticated user info

Projects

• list_projects - List all projects

• get_project - Get project details

• create_project - Create a new project

Tasks

• list_tasks - List tasks with filters (workspace, project, assignee, status, labels)

• get_task - Get task details

• create_task - Create a new task with full options (priority, duration, auto-scheduling)

• update_task - Update task properties

• delete_task - Delete a task

• move_task - Move task to different workspace/project

• unassign_task - Remove assignee from task

Recurring Tasks

• list_recurring_tasks - List recurring tasks

• create_recurring_task - Create recurring task with frequency patterns

• delete_recurring_task - Delete a recurring task

Comments

• get_comments - Get comments on a task

• create_comment - Add a comment to a task

Schedules & Statuses

• get_schedules - Get available schedules

• get_statuses - Get statuses for workspace/project

Custom Fields

• get_custom_fields - List custom fields

• create_custom_field - Create a custom field

• delete_custom_field - Delete a custom field

• add_custom_field_to_task - Add custom field value to task

• delete_custom_field_from_task - Remove custom field from task

• add_custom_field_to_project - Add custom field value to project

• delete_custom_field_from_project - Remove custom field from project

Guides

• get_frequency_guide - Get recurring task frequency pattern documentation

• get_api_guide - Get comprehensive API usage guide

🔑 Getting Your API Key

1. Log into Motion

2. Go to Settings → API

3. Create a new API key

4. Copy the key immediately (it's only shown once!)

🔌 Installation

Option 1: Deploy Your Own (Recommended)

This is the recommended approach because your Motion API key gives full access to your tasks and projects. Deploying your own instance keeps your key secure.

1. Click the "Deploy to Cloudflare Workers" button above

2. After deployment, add your API key as a secret:

   npx wrangler secret put MOTION_API_KEY

   Enter your Motion API key when prompted.

3. Your MCP will be available at: https://motion-mcp-cloudflare.<your-account>.workers.dev/sse

4. Connect to Claude Code:

   claude mcp add motion npx mcp-remote https://motion-mcp-cloudflare.<your-account>.workers.dev/sse

   Or add to Cursor settings (.cursor/mcp.json):

   {
     "mcpServers": {
       "motion": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://motion-mcp-cloudflare.<your-account>.workers.dev/sse"
         ]
       }
     }
   }

Option 2: Use the Public Server (Quick Start)

You can use the public server for quick testing. Since you'll need to provide your API key per-session, this is less convenient but requires no deployment.

Claude Code:

claude mcp add motion npx mcp-remote https://motion-mcp-cloudflare.jgentes.workers.dev/sse

Cursor:

Install in Cursor by copying this link into your browser:

cursor://anysphere.cursor-deeplink/mcp/install?name=motion&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJtY3AtcmVtb3RlIiwiaHR0cHM6Ly9tb3Rpb24tbWNwLWNsb3VkZmxhcmUuamdlbnRlcy53b3JrZXJzLmRldi9zc2UiXX0=

Or manually add to Cursor settings (.cursor/mcp.json):

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://motion-mcp-cloudflare.jgentes.workers.dev/sse"
      ]
    }
  }
}

Important: When using the public server, you must first call the set_api_key tool with your Motion API key before using any other tools:

Please set my Motion API key to: mot_xxxxxxxxxxxx

Your key is stored only for the duration of your session and is not persisted.

Option 3: Run Locally (Development)

# Clone the repository
git clone https://github.com/jgentes/motion-mcp-cloudflare.git
cd motion-mcp-cloudflare

# Install dependencies
npm install

# Create .dev.vars file with your API key
echo "MOTION_API_KEY=your-api-key-here" > .dev.vars

# Run locally (starts on http://localhost:8787)
npm run dev

Connect to your local instance:

Claude Code:

claude mcp add motion npx mcp-remote http://localhost:8787/sse

Cursor config:

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/sse"
      ]
    }
  }
}

📚 Example Usage

When connected to Claude Code or Cursor, you can ask questions like:

• "List all my Motion workspaces"

• "Show me all tasks in the Marketing project"

• "Create a task called 'Review Q4 budget' with high priority due tomorrow"

• "Set up a daily recurring task for my standup meeting"

• "Move all tasks from Project A to Project B"

• "What are the available statuses in my workspace?"

• "Add a comment to task XYZ with my progress update"

Creating Tasks with Auto-Scheduling

Create a task called "Write blog post" in my workspace with:
- Due date: next Friday
- Duration: 2 hours
- Priority: HIGH
- Auto-schedule it on my "Work Hours" schedule

Setting Up Recurring Tasks

Create a recurring task for "Weekly team meeting" that happens:
- Every Monday at the start of the week
- Duration: 1 hour
- Priority: MEDIUM

🔒 Security Considerations

• Deploy your own instance if you're using Motion for sensitive work. Your API key gives full access to your tasks, projects, and data.

• When using set_api_key on a public server, your key is stored in memory for the session only and is not logged or persisted.

• Never share your Motion API key or commit it to version control.

• Consider rotating your API key periodically in Motion Settings.

⏱️ Rate Limits

Motion's API has a rate limit of 12 requests per minute for individual accounts. The MCP will return rate limit errors if exceeded - simply wait and retry.

🔧 Customization

To modify the MCP server, edit src/index.ts:

• Add new tools using this.server.tool(...)

• Modify existing tool parameters or behavior

• Add custom guides or documentation

📦 Versioning & Releases

This project uses release-it with conventional changelog for versioning.

For Maintainers

To create a new release:

npm run release

Commit Message Format

Use Conventional Commits format:

• feat: add new task filtering - New features (minor version bump)

• fix: correct API endpoint - Bug fixes (patch version bump)

• docs: update installation guide - Documentation changes

• chore: update dependencies - Maintenance tasks

• BREAKING CHANGE: in commit body - Breaking changes (major version bump)

📄 License

MIT

🙏 Credits

• Built with Cloudflare Workers

• API powered by Motion

• Implements the Model Context Protocol

📖 Resources

• Motion API Reference

• Frequency Patterns Cookbook

• Rate Limits Documentation

• Motion Help Center