How do I use Motion MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Motion MCP Server add a high priority task to prepare the quarterly report by Friday" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

NPM Version License

Motion MCP Server

Motion is an AI-powered calendar and task management app that auto-schedules your work. This MCP server bridges Motion's API with LLMs like Claude and ChatGPT via the Model Context Protocol, so you can manage tasks, search projects, check your schedule, and more — all through natural conversation. It works on desktop, web, and mobile.

Preview

Click the image above to view full size

Getting Started

Prerequisites: Node.js 18+ and a Motion API key.

Local Setup (npx)

For desktop MCP clients — Claude Desktop, Claude Code, Cursor, and similar.

Add to your claude_desktop_config.json:

{ "mcpServers": { "motion": { "command": "npx", "args": ["motionmcp"], "env": { "MOTION_API_KEY": "your_api_key" } } } }

Test from the command line:

MOTION_API_KEY=your_api_key npx motionmcp

Tip: npx always runs the latest published version — no install needed.

Remote Setup (Cloudflare Workers)

For mobile and web clients — Claude mobile/web, ChatGPT mobile/web, or any HTTP MCP client.

One-click deploy

Deploy to Cloudflare Workers

After deploy, set your secrets in the Cloudflare dashboard (Workers > your worker > Settings > Variables):

MOTION_API_KEY — your Motion API key
MOTION_MCP_SECRET — a random string (generate with openssl rand -hex 16)

Manual deploy

# Set secrets npx wrangler secret put MOTION_API_KEY npx wrangler secret put MOTION_MCP_SECRET # use: openssl rand -hex 16 # Deploy npm run worker:deploy

Your MCP URL will be:

https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp/YOUR_SECRET

Connecting from Claude

Go to claude.ai > Settings > Connectors
Add your MCP URL
The server syncs automatically to the Claude mobile app

Connecting from ChatGPT

Go to ChatGPT Settings > Connectors
Add your MCP URL

Security: The secret in the URL prevents casual discovery. Treat the full URL like a password — don't share it publicly.

Tool configuration works the same as the local server. Set MOTION_MCP_TOOLS in wrangler.toml under [vars], or override via wrangler secret put MOTION_MCP_TOOLS.

For local Worker development, see DEVELOPER.md.

API Key

The server reads your Motion API key from the MOTION_API_KEY environment variable.

Inline (npx):

MOTION_API_KEY=your-key npx motionmcp

.env

MOTION_API_KEY=your-key

When using npx, prefer the inline environment variable since npx won't read a local .env file.

Tool Configuration

All 10 tools are enabled by default. If you run multiple MCP servers and want to reduce tool selection noise, you can limit which tools are exposed via the MOTION_MCP_TOOLS environment variable:

Level	Tools	Description
minimal	3	Tasks, projects, workspaces only
essential	7	Adds users, search, comments, schedules
complete (default)	10	Full API access including custom fields, recurring tasks, statuses
custom	varies	Pick exactly the tools you need

Custom example:

MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npx motionmcp

Tools Reference

motion_tasks

Operations: create, list, get, update, delete, move, unassign

The primary tool for task management. Supports all Motion API parameters including name, description, priority, dueDate, duration, labels, assigneeId, and autoScheduled. You can reference workspaces and projects by name — the server resolves them automatically.

{ "operation": "create", "name": "Complete API integration", "workspaceName": "Development", "projectName": "Release Cycle Q2", "dueDate": "2025-06-15T09:00:00Z", "priority": "HIGH", "labels": ["api", "release"] }

motion_projects

Operations: create, list, get

Manage Motion projects. Workspace and project names are fuzzy-matched, and the server auto-selects your "Personal" workspace if none is specified.

{"operation": "create", "name": "New Project", "workspaceName": "Personal"}

motion_workspaces

Operations: list, get, set_default

List and inspect workspaces, or set a default workspace for subsequent calls.

motion_users

Operations: list, current

List users in a workspace or get the current authenticated user.

motion_search

Operations: content, context, smart

Cross-search tasks and projects by query with intelligent scope and priority boosting. The context operation returns a lightweight summary of your workspace (tasks, projects, schedules) — useful for giving an LLM situational awareness. The smart operation combines search with prioritized scheduling to surface what's most relevant.

{"operation": "content", "query": "API integration", "workspaceName": "Development"}

motion_comments

Operations: list, create

Read and add comments on tasks and projects.

{"operation": "create", "taskId": "task_123", "content": "Updated the API endpoints as discussed"}

motion_schedules

Operations: list

Retrieve user schedules and time zones. Supports prioritized scheduling with conflict detection and workload breakdowns by status, priority, and project.

motion_custom_fields

Operations: list, create, delete, add_to_project, remove_from_project, add_to_task, remove_from_task

Define and manage custom fields across workspaces, projects, and tasks.

{ "operation": "create", "name": "Sprint", "type": "DROPDOWN", "options": ["Sprint 1", "Sprint 2", "Sprint 3"], "workspaceName": "Development" }

motion_recurring_tasks

Operations: list, create, delete

Manage recurring task templates.

{ "operation": "create", "name": "Weekly Team Standup", "recurrence": "WEEKLY", "projectName": "Team Meetings", "daysOfWeek": ["MONDAY", "WEDNESDAY", "FRIDAY"], "duration": 30 }

motion_statuses

Operations: list

List available statuses for a workspace.

Advanced Configuration

Minimal setup (3 tools only):

{ "mcpServers": { "motion": { "command": "npx", "args": ["motionmcp"], "env": { "MOTION_API_KEY": "your_api_key", "MOTION_MCP_TOOLS": "minimal" } } } }

Custom tools selection:

{ "mcpServers": { "motion": { "command": "npx", "args": ["motionmcp"], "env": { "MOTION_API_KEY": "your_api_key", "MOTION_MCP_TOOLS": "custom:motion_tasks,motion_projects,motion_search" } } } }

Using your local workspace (npm):

{ "mcpServers": { "motion": { "command": "npm", "args": ["run", "mcp:dev"], "cwd": "/absolute/path/to/your/MotionMCP", "env": { "MOTION_API_KEY": "your_api_key" } } } }

See the full developer setup in DEVELOPER.md.

Debugging

Logs output to stderr in JSON format
Check for missing keys, workspace/project names, and permissions
Use motion_workspaces (list) and motion_projects (list) to validate IDs

{ "level": "info", "msg": "Task created successfully", "method": "createTask", "taskId": "task_789", "workspace": "Development" }

License

Apache-2.0 License

For more information, see the full Motion API docs or Model Context Protocol docs.

Motion MCP Server

Motion MCP Server

Preview

Getting Started

Local Setup (npx)

Remote Setup (Cloudflare Workers)

One-click deploy

Manual deploy

Connecting from Claude

Connecting from ChatGPT

API Key

Tool Configuration

Tools Reference

motion_tasks

motion_projects

motion_workspaces

motion_users

motion_search

motion_comments

motion_schedules

motion_custom_fields

motion_recurring_tasks

motion_statuses

Advanced Configuration

Debugging

License

Resources

Tools

Latest Blog Posts

MCP directory API