Motion MCP Server
Motion MCP Server bridges the Motion calendar/task API with MCP clients (Claude, ChatGPT, Cursor, etc.), exposing 10 tools for conversational task, project, and schedule management.
motion_tasks — create, list, get, update, delete, move, unassign, and list_all_uncompleted tasks; supports names, descriptions, priority, due dates, duration, labels, assignees, auto-scheduling, status/completion filters, and cross-workspace queries.
motion_projects — create, list, and get projects, including creation from templates with stages and variable instances; supports workspace and project name fuzzy matching.
motion_workspaces — list and get workspaces.
motion_users — list users in a workspace or fetch the current authenticated user.
motion_search — search tasks and/or projects by query, optionally scoped to a workspace.
motion_comments — list and create comments on tasks.
motion_custom_fields — define and manage custom fields (list, create, delete, add/remove on projects and tasks) with types like text, date, person, select, number, and more.
motion_recurring_tasks — list, create, and delete recurring task templates with daily/weekly/biweekly/monthly/quarterly/yearly/custom frequencies.
motion_schedules — list recurring working-hour schedules and time zones (templates only, not actual calendar events).
motion_statuses — list available task/project statuses for a workspace.
Configure tool exposure via
MOTION_MCP_TOOLS(minimal, essential, complete, or custom) and run locally via npx or remotely on Cloudflare Workers over Streamable HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Motion MCP Server create a task to review design docs due tomorrow at 3pm"
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.
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
Related MCP server: ClickUp MCP Server
Getting Started
Prerequisites: Node.js 20+ 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 motionmcpTip:
npxalways 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
After deploy, set your secrets in the Cloudflare dashboard (Workers > your worker > Settings > Variables):
MOTION_API_KEY— your Motion API keyMOTION_MCP_SECRET— a random string (generate withopenssl 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:deployYour MCP URL will be:
https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp/YOUR_SECRETUse exactly that address. The secret goes at the end of the path and nothing follows it. The server speaks MCP Streamable HTTP on that single endpoint; do not append /sse or any other sub-path.
Clients that can send headers can keep the secret out of the URL instead: point them at https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp and send Authorization: Bearer YOUR_SECRET.
Connecting from Claude
Go to claude.ai > Settings > Connectors
Add your MCP URL
The server syncs automatically to the Claude mobile app
For Claude Code, use the Streamable HTTP transport:
claude mcp add --transport http motion https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp --header "Authorization: Bearer YOUR_SECRET"In Claude Desktop, add the same URL as a remote server of type http (not sse).
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.
Transport: Only Streamable HTTP is served. The older HTTP+SSE transport (a
GETstream plus a/messageendpoint) was retired in the move to a stateless server; a client configured with transport typessemust be switched tohttp.
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 file (when running from source via npm):
MOTION_API_KEY=your-keyWhen using
npx, prefer the inline environment variable sincenpxwon't read a local.envfile.
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 | 8 | Adds users, search, comments, schedules, statuses |
complete (default) | 10 | Full API access including custom fields and recurring tasks |
custom | varies | Pick exactly the tools you need |
Custom example:
MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npx motionmcpTools Reference
motion_tasks
Operations: create, list, list_all_uncompleted, 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.
list_all_uncompleted spans every workspace in one call (it ignores workspaceId/workspaceName) and honors the dueDate and priority filters, so "what's due this week across all my workspaces?" resolves directly. On list, dueDate is an inclusive on-or-before-day bound that includes overdue tasks (so dueDate: "today" answers "what's due today?"), and completedAfter / completedBefore bound by completion date in your account's time zone for "what did I get done this week?". Dates are interpreted in your Motion account's time zone, and list responses lead with a header naming that zone and today's local date.
{
"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"}create also accepts dueDate and priority. To create from a project template, pass projectDefinitionId plus a stages array with one entry per template stage, in order (the count must match the template). Read the IDs from an existing project via get, which returns ProjectDefinitionId and Stages[].stageDefinitionId.
{"operation": "create", "name": "Client Onboarding", "workspaceName": "Personal",
"projectDefinitionId": "pde_...",
"stages": [
{"stageDefinitionId": "std_...", "dueDate": "2026-11-01"},
{"stageDefinitionId": "std_...", "dueDate": "2026-11-15",
"variableInstances": [{"variableName": "Owner", "value": "<user ID>"}]}
]}motion_workspaces
Operations: list, get
List and inspect workspaces.
motion_users
Operations: list, current
List users in a workspace or get the current authenticated user.
motion_search
Operations: content
Search tasks and projects by query across a workspace.
{"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, showing each day's working hours (start-end per day) and time zones. These are recurring working-hour templates only — they do not expose actual calendar events or meetings, so they cannot by themselves show a true free/busy picture; combine with tasks' scheduledStart/scheduledEnd to see what Motion has auto-booked.
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
stderrin JSON formatCheck for missing keys, workspace/project names, and permissions
Use
motion_workspaces(list) andmotion_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.
Available Tools
10 toolsmotion_commentsC
Manage comments on tasks
Inputs: taskId (required), operation (required), cursor, content.
motion_custom_fieldsB
Manage custom fields for tasks and projects. Required params per operation: list: workspaceId or workspaceName. create: workspaceId/workspaceName + name + field (type); options[] also required for select/multiSelect. delete: workspaceId/workspaceName + fieldId. add_to_project: projectId + fieldId. remove_from_project: projectId + valueId. add_to_task: taskId + fieldId. remove_from_task: taskId + valueId.
Inputs: operation (required), name, field, value, +8 more.
motion_projectsC
Manage Motion projects - supports create, list, and get operations
Inputs: operation (required), name, projectId, description, +3 more.
motion_recurring_tasksA
Manage recurring tasks. Required params per operation: list: workspaceId or workspaceName. create: workspaceId/workspaceName + name + assigneeId + frequency (with frequency.type). delete: recurringTaskId.
Inputs: operation (required), name, duration, priority, +11 more.
motion_schedulesA
Get all schedules showing each day's working hours (start-end per day) and time zones. The Motion API returns all schedules with no filtering options. These are recurring working-hour templates only — they do NOT expose actual calendar events or meetings, so they cannot by themselves show a true free/busy picture; combine with tasks' scheduledStart/scheduledEnd to see what Motion has auto-booked.
Inputs: operation.
motion_searchB
Search Motion tasks and projects by query
Inputs: operation (required), limit, query, searchScope, +2 more.
motion_statusesA
Get available task/project statuses for a workspace
Inputs: operation, workspaceId, workspaceName.
motion_tasksC
Manage Motion tasks - supports create, list, get, update, delete, move, unassign, and list_all_uncompleted operations
Inputs: operation (required), name, limit, labels, +17 more.
motion_usersC
Manage users and get current user information
Inputs: operation (required), teamId, workspaceId, workspaceName.
motion_workspacesA
Manage Motion workspaces - supports list and get operations
Inputs: operation (required), workspaceId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct Motion resource (tasks, projects, recurring tasks, schedules, statuses, workspaces, users, comments, custom fields), so boundaries are generally clear. The main potential overlap is between motion_search and the list operations of motion_tasks/motion_projects, but the search description clarifies its query-based purpose.
Every tool follows the identical motion_<resource> pattern with a consistent prefix and snake_case resource nouns. The convention is resource-oriented rather than verb_noun, but it is applied uniformly across all ten tools.
Ten tools is well-scoped for a project/task management server, with each tool mapping to a coherent domain resource. No tool feels redundant or artificially split.
Tasks have full lifecycle coverage (create/list/get/update/delete/move/unassign), and custom fields, comments, statuses, and search round out the surface well. However, projects lack update/delete, recurring tasks lack update/get, and there is no subtask support, leaving minor gaps agents must work around.
Maintenance
Related MCP Connectors
Manage projects, tasks, time tracking, and team collaboration through natural language.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with ClickUp's task management API for core project workflows, supporting operations like task creation, updates, search, assignment, and team analytics through natural language.285MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with ClickUp's project management platform. Supports comprehensive task management, workspace administration, and list operations through natural language commands.-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables comprehensive Asana workspace management through natural language, supporting task tracking, project planning, team collaboration, and workflow automation across workspaces, projects, sections, and tasks.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Todoist tasks, projects, sections, and labels through natural language, supporting task creation, updates, completion, and intelligent organization of your workflow.17 npmMIT