Motion MCP Server

Unofficial Model Context Protocol (MCP) server for Motion - the AI-powered calendar, task management, and project planning app that automatically schedules your work.

Note: This is a community-built integration, not an official Motion product. We created this MCP server because there was no official implementation available, enabling AI assistants like Claude to interact with Motion's powerful scheduling and task management features.

Claude Desktop vs Claude Code

Important: There are two different Claude applications that can use this MCP server:

• 🖥️ Claude Desktop: The desktop application you download and install on your computer
• ⌨️ Claude Code: A command-line interface (CLI) tool for developers

Each has different installation procedures - make sure you follow the correct instructions for your application!

Quick Start

Step 1: Get Your Motion API Key

1. Log into Motion
2. Navigate to Settings → API
3. Create a new API key
4. Copy the key immediately (it's only shown once!)

Step 2: Choose Your Claude Application

Important: This MCP server works with both Claude applications, but they have different installation methods:

• Claude Desktop (Desktop App): Requires manual JSON configuration
• Claude Code (CLI Tool): Has built-in MCP installation commands

Choose the installation method below based on which Claude application you're using.

---

Installation for Claude Desktop (Desktop App)

Manual Configuration

1. Find your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/claude/claude_desktop_config.json

2. Add the following to your configuration file:

{
  "mcpServers": {
    "motion": {
      "command": "npx",
      "args": ["-y", "@rf-d/motion-mcp"],
      "env": {
        "MOTION_API_KEY": "your_motion_api_key_here",
        "MOTION_RATE_LIMIT_PER_MINUTE": "12"
      }
    }
  }
}

3. Replace your_motion_api_key_here with your actual Motion API key
4. Restart Claude Desktop for the changes to take effect

---

Installation for Claude Code (CLI Tool)

Step 1: Install Claude Code CLI

First, install the Claude Code CLI if you haven't already:

npm install -g @anthropic-ai/claude-code

Step 2: Add Motion MCP Server

Run this command to add the Motion MCP server to Claude Code:

claude mcp add motion npx -- -y @rf-d/motion-mcp

Step 3: Configure Your API Key

Set your Motion API key as an environment variable:

export MOTION_API_KEY="your_motion_api_key_here"

Or create a .env file in your project directory:

echo "MOTION_API_KEY=your_motion_api_key_here" > .env

---

Alternative Installation Methods

Via GitHub (Development)

For development installation, we recommend using mjaskolski's fork which is up-to-date, has fewer errors, full documentation, and comprehensive tests:

git clone https://github.com/mjaskolski/motion-mcp.git
cd motion-mcp
npm install
npm run build

# Create a .env file with your API key
echo "MOTION_API_KEY=your_motion_api_key_here" > .env

# Run in development mode
npm run dev

For Claude Desktop (development version):

{
  "mcpServers": {
    "motion": {
      "command": "npm",
      "args": [
        "--prefix",
        "/path/to/your/motion-mcp",
        "--silent",
        "run",
        "start"
      ],
      "env": {
        "MOTION_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

For Claude Code (development version):

claude mcp add motion-dev npm -- --prefix /path/to/your/motion-mcp --silent run start

Replace /path/to/your/motion-mcp with the actual path to your cloned repository.

Features

Core Capabilities

• Task Management: Create, update, delete, and organize tasks with full support for Motion's auto-scheduling
• Project Management: Create and view projects across workspaces (Note: Projects are read-only once created)
• Workspace Organization: Access and manage multiple workspaces
• Team Collaboration: User management, task assignment, and team coordination
• Comments: Add and manage task comments for better collaboration
• Scheduling: View and manage schedules with Motion's intelligent scheduling
• Custom Fields: Create and manage custom fields for tasks and projects
• Recurring Tasks: Set up and manage recurring tasks with flexible patterns

Rate Limiting

The server includes automatic rate limiting to comply with Motion's API limits:

• Individual accounts: 12 requests per minute
• Team accounts: 120 requests per minute
• Enterprise accounts: Custom limits

Available Tools

Task Management (7 tools)

• motion_list_tasks - List tasks with filtering and pagination
• motion_get_task - Get detailed task information
• motion_create_task - Create new tasks with auto-scheduling
• motion_update_task - Update task properties
• motion_delete_task - Delete tasks
• motion_move_task - Move tasks between workspaces
• motion_unassign_task - Remove assignee from task

Project Management (3 tools)

• motion_list_projects - List all projects
• motion_get_project - Get project details
• motion_create_project - Create new projects

Workspace Tools (2 tools)

• motion_list_workspaces - List accessible workspaces
• motion_get_workspace - Get workspace details

Additional Tools (22 tools)

• User management (3 tools)
• Schedule management (1 tool)
• Comment management (5 tools)
• Custom field management (5 tools)
• Recurring task management (4 tools)
• Schedule management (2 tools)
• Status management (1 tool)

Usage Examples

Basic Task Creation

Create a new task called "Review Q4 reports" due tomorrow with high priority

Advanced Task Management

List all my incomplete tasks in the "Development" project and move any bug fixes to high priority

Team Collaboration

Show me all tasks assigned to the team this week and add a comment to each one about the sprint goals

Recurring Tasks

Create a weekly recurring task for team standup meetings every Monday at 9 AM

Development

Prerequisites

• Node.js >= 20.0.0
• npm or yarn
• Motion API key

Setup

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

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API key

# Run in development mode
npm run dev

Scripts

• npm run build - Build for production
• npm run dev - Development mode with hot reload
• npm run typecheck - TypeScript type checking
• npm run lint - ESLint code linting
• npm run format - Prettier code formatting

Project Structure

src/
├── api/
│   └── client.ts          # Motion API client with rate limiting
├── tools/
│   ├── task.ts           # Task management tools
│   ├── project.ts        # Project management tools
│   ├── workspace.ts      # Workspace tools
│   └── ...               # Other tool categories
├── types/
│   ├── motion.ts         # Motion API type definitions
│   └── tool.ts           # MCP tool type definitions
├── config.ts             # Configuration management
└── index.ts              # Main server entry point

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass
• Code follows the existing style
• TypeScript types are properly defined
• Documentation is updated

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

• Motion API Documentation
• Model Context Protocol
• Motion Website

Disclaimer

This is an unofficial integration and is not affiliated with, officially maintained, or endorsed by Motion. Use at your own discretion.

Troubleshooting

Common Issues

"Motion API key not found" error

• Claude Desktop: Make sure you've added the MOTION_API_KEY to your claude_desktop_config.json configuration
• Claude Code: Ensure your API key is set as an environment variable or in a .env file
• Verify the key is correct and hasn't expired
• Restart the application after adding the key

"Rate limit exceeded" error

• Individual accounts are limited to 12 requests per minute
• Team accounts get 120 requests per minute
• The server automatically handles rate limiting, but very heavy usage may still hit limits

"Command not found" error

• Make sure you have Node.js >= 20.0.0 installed
• Claude Desktop: Try running with the full path: npx @rf-d/motion-mcp
• Claude Code: Ensure the Claude Code CLI is installed: npm install -g @anthropic-ai/claude-code

Claude Desktop configuration file not found

• The configuration file is created automatically when you first run Claude Desktop
• If it doesn't exist, create it manually at the correct location for your operating system
• Ensure the JSON syntax is valid (no trailing commas, proper brackets)

Claude Code MCP server not loading

• Run claude mcp list to see if the server is properly registered
• Check that your API key environment variable is set correctly
• Try removing and re-adding the server: claude mcp remove motion && claude mcp add motion npx -- -y @rf-d/motion-mcp

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• NPM Package: npmjs.com/package/@rf-d/motion-mcp

Need Help Identifying Your Claude Application?

• Claude Desktop: If you downloaded and installed a desktop app from claude.ai
• Claude Code: If you installed it with npm install -g @anthropic-ai/claude-code and run it with the claude command

---

Built with love for the Motion and MCP communities