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., "@usemotion-mcp-server list tasks assigned to me"
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.
MCP server for the Motion API, running on Bun. Supports two transports, selected with the MCP_TRANSPORT environment variable:
stdio (default) — local use; reads MOTION_API_KEY from the environment
http — streamable HTTP, deployable to Vercel; each client sends its own Motion API key as a request header (X-API-Key or Authorization: Bearer), which is forwarded to the Motion API for that request only. The server stores no credentials; requests without a key get a 401.
Create an API key in Motion (Settings → API).
For stdio mode, create a .env file in the project root:
cp .env.example .env # then fill in MOTION_API_KEYInstall dependencies:
bun installRelated MCP server: Motion MCP Server
Compile a standalone binary (no Bun required at runtime):
bun run compile # produces bin/usemotion-mcp-serverThe binary still auto-loads .env from the directory it runs in; otherwise set MOTION_API_KEY in its environment.
MCP_TRANSPORT=http bun run src/index.ts # serves http://localhost:3000/api/mcp (PORT to override)Clients authenticate per request:
claude mcp add --transport http motion http://localhost:3000/api/mcp --header "X-API-Key: your-key-here"api/mcp.ts + vercel.json ("bunVersion": "1.x") make the repo deployable as-is:
vercel deploy # then connect clients to https://<your-app>.vercel.app/api/mcpDo not set MOTION_API_KEY on the deployment — keys come from client headers and are never stored.
claude mcp add motion -- bun run /path/to/usemotion-mcp-server/src/index.tsAdd to claude_desktop_config.json:
{
"mcpServers": {
"motion": {
"command": "bun",
"args": ["run", "/path/to/usemotion-mcp-server/src/index.ts"],
"env": { "MOTION_API_KEY": "your-key-here" }
}
}
}Note: Bun auto-loads .env from the working directory, so the env block is only needed if the server isn't started from the project root.
Tool | Description |
| List tasks with filters (workspace, project, status, assignee, name, label) |
| Get a task by id |
| Create a task (supports auto-scheduling, priority, labels, markdown description) |
| Update a task |
| Delete a task |
| Move a task to another workspace |
| Remove a task's assignee |
| List projects in a workspace |
| Get a project by id |
| Create a project |
| List workspaces |
| List users (find assignee ids) |
| Get the user tied to the API key |
| List task statuses in a workspace |
| Get schedules used by auto-scheduling |
| List comments on a task |
| Comment on a task |
Motion's rate limit is 12 requests/minute on individual plans; the client retries 429s with backoff (honors Retry-After).
List endpoints are cursor-paginated: pass cursor from the previous response's meta.nextCursor.
bun run typecheck # tsc --noEmit
bun run scripts/smoke.ts # stdio smoke test: lists tools, then create → get → update → delete a task
bun run scripts/smoke-http.ts # HTTP smoke test: 401 without key, then list tools + workspaces via header auth
# (start the server first: MCP_TRANSPORT=http bun run src/index.ts)This server cannot be deployed
Read teams, spaces, lists and tasks; create, update and comment on tasks and track time.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Read tasks, habits, events and scheduling links; create and update Reclaim tasks and habits.