# Motion MCP Server

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

## 🚀 Quick Deploy

[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/jgentes/motion-mcp-cloudflare)

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.

## 📋 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](https://app.usemotion.com)
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:
   ```bash
   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:
   ```bash
   claude mcp add motion npx mcp-remote https://motion-mcp-cloudflare.<your-account>.workers.dev/sse
   ```
   
   Or add to Cursor settings (`.cursor/mcp.json`):
   ```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:**
```bash
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`):
```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)

```bash
# 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:**
```bash
claude mcp add motion npx mcp-remote http://localhost:8787/sse
```

**Cursor config:**
```json
{
  "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:
```bash
npm run release
```

### Commit Message Format

Use [Conventional Commits](https://www.conventionalcommits.org/) 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](https://workers.cloudflare.com/)
- API powered by [Motion](https://usemotion.com)
- Implements the [Model Context Protocol](https://modelcontextprotocol.io/)

## 📖 Resources

- [Motion API Reference](https://docs.usemotion.com/api-reference)
- [Frequency Patterns Cookbook](https://docs.usemotion.com/cookbooks/frequency/)
- [Rate Limits Documentation](https://docs.usemotion.com/cookbooks/rate-limits/)
- [Motion Help Center](https://help.usemotion.com/)