# Motion — how to use (mcp.ai)

Connect your Motion account and use 27 tools for productivity straight from your AI agent. Connect with your own API key. Motion is an intelligent calendar and project management tool that automatically plans your day, schedules meetings, and helps teams collaborate efficiently.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_motion?ms=1787291460000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `motion_add_custom_field_to_project`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/motion`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/motion/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/motion/add/custom/field/to/project` — Tool to add a custom field value to a project in Motion. Use when you need to set or update custom field data on an existing project.
  - body: { value: object, projectId: string, customFieldInstanceId: string }
- `POST https://api.mcp.ai/api/motion/add/custom/field/to/task` — Tool to add a custom field value to a task in Motion. Use when you need to set or update custom field data on an existing task.
  - body: { value: object, taskId: string, customFieldInstanceId: string }
- `POST https://api.mcp.ai/api/motion/create/comment` — Tool to create a new comment on a Motion task. Use when you need to add a comment to an existing task.
  - body: { taskId: string, content?: string }
- `POST https://api.mcp.ai/api/motion/create/custom/field` — Tool to create a new custom field in a Motion workspace. Use when you need to add custom fields like text, select options, dates, or other field types to customize your workspace. For select/multiSele
  - body: { name: string, type: string, metadata?: object, workspaceId: string }
- `POST https://api.mcp.ai/api/motion/create/project` — Tool to create a new project in Motion. Use when you need to create a project within a specific workspace. Projects can have optional due dates, descriptions (HTML supported), labels, and priority lev
  - body: { name: string, labels?: string[], stages?: object[], dueDate?: string, priority?: string, description?: string, workspaceId: string, projectDefinitionId?: string }
- `POST https://api.mcp.ai/api/motion/create/recurring/task` — Tool to create a new recurring task in Motion. Use when you need to set up tasks that repeat on a schedule (daily, weekly, monthly, etc.). Recurring tasks automatically generate task instances based o
  - body: { name: string, duration?: integer, priority?: string, schedule?: string, frequency: string, idealTime?: string, assigneeId: string, startingOn?: string, description?: string, workspaceId: string, deadlineType?: string }
- `POST https://api.mcp.ai/api/motion/create/task` — Tool to create a new task in Motion. Use when you need to add a task to a workspace with specified properties like name, priority, due date, and assignee.
  - body: { name: string, labels?: string[], status?: string, dueDate?: string, duration?: string, priority?: string, projectId?: string, assigneeId?: string, description?: string, workspaceId: string }
- `POST https://api.mcp.ai/api/motion/delete/custom/field` — Tool to delete a custom field from Motion workspace. Use when you need to remove a custom field that is no longer needed. This operation is permanent and cannot be undone.
  - body: { id: string, workspaceId: string }
- `POST https://api.mcp.ai/api/motion/delete/custom/field/from/project` — Tool to delete a custom field value from a project in Motion. Use when you need to remove a custom field value from a specific project.
  - body: { valueId: string, projectId: string }
- `POST https://api.mcp.ai/api/motion/delete/custom/field/from/task` — Tool to delete a custom field value from a task in Motion. Use when you need to remove a custom field value from a specific task by providing the task ID and custom field value ID.
  - body: { taskId: string, valueId: string }
- `POST https://api.mcp.ai/api/motion/delete/recurring/task` — Tool to delete a recurring task from Motion based on the ID supplied. Use when you need to remove a recurring task permanently from the system.
  - body: { id: string }
- `POST https://api.mcp.ai/api/motion/delete/task` — Tool to delete a task from Motion based on task ID. Use when you need to permanently remove a task from the Motion workspace.
  - body: { id: string }
- `POST https://api.mcp.ai/api/motion/get/my/user` — Tool to get information on the owner of the API key. Use when you need to retrieve the current user's profile details including their ID, name, and email address.
- `POST https://api.mcp.ai/api/motion/get/project` — Tool to retrieve a single project by its ID. Use when you need to get detailed information about a specific project including its name, description, status, and custom field values.
  - body: { id: string }
- `POST https://api.mcp.ai/api/motion/get/task` — Tool to retrieve a task by its ID from Motion. Returns complete task details including title, description, due date, priority, assignees, scheduling information, and custom fields.
  - body: { id: string }
- `POST https://api.mcp.ai/api/motion/list/comments` — Tool to get all comments on a specific task. Use when you need to retrieve comment history for a task. Supports cursor-based pagination for tasks with many comments.
  - body: { cursor?: string, taskId: string }
- `POST https://api.mcp.ai/api/motion/list/custom/fields` — Tool to retrieve all custom fields for a given Motion workspace. Use when you need to see what custom fields are available in a workspace.
  - body: { workspace_id: string }
- `POST https://api.mcp.ai/api/motion/list/projects` — Tool to get all projects for a workspace. Use when you need to retrieve all projects accessible to the API key, optionally filtered by workspace.
  - body: { cursor?: string, workspace_id?: string }
- `POST https://api.mcp.ai/api/motion/list/recurring/tasks` — Tool to get all recurring tasks for a workspace. Use when you need to retrieve recurring task information from Motion.
  - body: { cursor?: string, workspaceId: string }
- `POST https://api.mcp.ai/api/motion/list/schedules` — Tool to get a list of schedules for your user. Use when you need to retrieve the user's scheduling configuration including work hours and timezone settings.
- `POST https://api.mcp.ai/api/motion/list/statuses` — Tool to get a list of statuses for a Motion workspace. Use when you need to retrieve available task statuses for a workspace.
  - body: { workspaceId?: string }
- `POST https://api.mcp.ai/api/motion/list/tasks` — Tool to get all tasks for a given query with optional filtering. Use when you need to retrieve tasks from Motion, optionally filtered by assignee, project, workspace, status, label, or name.
  - body: { name?: string, label?: string, cursor?: string, status?: string[], projectId?: string, assigneeId?: string, workspaceId?: string, includeAllStatuses?: boolean }
- `POST https://api.mcp.ai/api/motion/list/users` — Tool to get a list of users for a given workspace or team. Use when you need to retrieve user information from Motion. Supports pagination via cursor and filtering by workspaceId or teamId.
  - body: { cursor?: string, teamId?: string, workspaceId?: string }
- `POST https://api.mcp.ai/api/motion/list/workspaces` — Tool to retrieve all workspaces a user has access to. Use when you need to discover available workspaces, filter for specific workspace IDs, or paginate through workspace results. Returns workspace de
  - body: { ids?: string[], cursor?: string }
- `POST https://api.mcp.ai/api/motion/move/task` — Tool to move a task to a different workspace in Motion. Use when you need to relocate a task from one workspace to another.
  - body: { id: string, assigneeId?: string, workspaceId: string }
- `POST https://api.mcp.ai/api/motion/unassign/task` — Tool to unassign a task from its current assignee. Use when you need to remove the assignee from a task, leaving the task unassigned.
  - body: { id: string }
- `POST https://api.mcp.ai/api/motion/update/task` — Tool to update an existing task in Motion. Use when you need to modify task properties like name, priority, due date, status, or assignee. Only provide the fields you want to update.
  - body: { id: string, name?: string, labels?: string[], status?: string, dueDate?: string, duration?: integer|string, priority?: string, projectId?: string, assigneeId?: string, description?: string, autoScheduled?: object }

## Example prompts
- "What can I do in Motion?"
- "Show me a summary of my Motion account"

## More
- Page: https://mcp.ai/motion
- Agent spec (llms.txt): https://mcp.ai/motion/llms.txt
- Postman collection: https://mcp.ai/motion/postman.json