Skip to content
Back to search

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…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jungle-busters--motion-mcp-server/badge.svg)](/listings/jungle-busters--motion-mcp-server)

HTML

<a href="/listings/jungle-busters--motion-mcp-server"><img src="/api/listings/jungle-busters--motion-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** Node.js 20+ and a [Motion API key](https://app.usemotion.com/settings/api).

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

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

Use 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

1. Go to [claude.ai](https://claude.ai) > Settings > Connectors 2. Add your MCP URL 3. 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

1. Go to ChatGPT Settings > Connectors 2. 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 `GET` stream plus a `/message` endpoint) was retired in the move to a stateless server; a client configured with transport type `sse` must be switched to `http`.

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](./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-key

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 310 lines
  1. ![NPM Version](https://img.shields.io/npm/v/motionmcp)
  2. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. # Motion MCP Server
  4. [Motion](https://www.usemotion.com/) 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](https://modelcontextprotocol.io/docs/), so you can manage tasks, search projects, check your schedule, and more — all through natural conversation. It works on desktop, web, and mobile.
  5. ## Preview
  6. <a href="sample.png"><img src="sample.png" alt="Motion MCP Server Preview" width="400" /></a>
  7. *Click the image above to view full size*
  8. ## Getting Started
  9. **Prerequisites:** Node.js 20+ and a [Motion API key](https://app.usemotion.com/settings/api).
  10. ### Local Setup (npx)
  11. For desktop MCP clients — Claude Desktop, Claude Code, Cursor, and similar.
  12. Add to your `claude_desktop_config.json`:
  13. ```json
  14. {
  15. "mcpServers": {
  16. "motion": {
  17. "command": "npx",
  18. "args": ["motionmcp"],
  19. "env": {
  20. "MOTION_API_KEY": "your_api_key"
  21. }
  22. }
  23. }
  24. }
  25. ```
  26. Test from the command line:
  27. ```bash
  28. MOTION_API_KEY=your_api_key npx motionmcp
  29. ```
  30. > **Tip:** `npx` always runs the latest published version — no install needed.
  31. ### Remote Setup (Cloudflare Workers)
  32. For mobile and web clients — Claude mobile/web, ChatGPT mobile/web, or any HTTP MCP client.
  33. #### One-click deploy
  34. [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/devondragon/MotionMCP)
  35. After deploy, set your secrets in the Cloudflare dashboard (Workers > your worker > Settings > Variables):
  36. - `MOTION_API_KEY` — your Motion API key
  37. - `MOTION_MCP_SECRET` — a random string (generate with `openssl rand -hex 16`)
  38. #### Manual deploy
  39. ```bash
  40. # Set secrets
  41. npx wrangler secret put MOTION_API_KEY
  42. npx wrangler secret put MOTION_MCP_SECRET # use: openssl rand -hex 16
  43. # Deploy
  44. npm run worker:deploy
  45. ```
  46. Your MCP URL will be:
  47. ```
  48. https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp/YOUR_SECRET
  49. ```
  50. Use 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.
  51. 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`.
  52. #### Connecting from Claude
  53. 1. Go to [claude.ai](https://claude.ai) > Settings > Connectors
  54. 2. Add your MCP URL
  55. 3. The server syncs automatically to the Claude mobile app
  56. For Claude Code, use the Streamable HTTP transport:
  57. ```bash
  58. claude mcp add --transport http motion https://motion-mcp-server.YOUR_SUBDOMAIN.workers.dev/mcp --header "Authorization: Bearer YOUR_SECRET"
  59. ```
  60. In Claude Desktop, add the same URL as a remote server of type `http` (not `sse`).
  61. #### Connecting from ChatGPT
  62. 1. Go to ChatGPT Settings > Connectors
  63. 2. Add your MCP URL
  64. > **Security:** The secret in the URL prevents casual discovery. Treat the full URL like a password — don't share it publicly.
  65. > **Transport:** Only Streamable HTTP is served. The older HTTP+SSE transport (a `GET` stream plus a `/message` endpoint) was retired in the move to a stateless server; a client configured with transport type `sse` must be switched to `http`.
  66. 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`.
  67. For local Worker development, see [DEVELOPER.md](./DEVELOPER.md).
  68. ### API Key
  69. The server reads your Motion API key from the `MOTION_API_KEY` environment variable.
  70. **Inline (npx):**
  71. ```bash
  72. MOTION_API_KEY=your-key npx motionmcp
  73. ```
  74. **`.env` file (when running from source via npm):**
  75. ```bash
  76. MOTION_API_KEY=your-key
  77. ```
  78. > When using `npx`, prefer the inline environment variable since `npx` won't read a local `.env` file.
  79. ## Tool Configuration
  80. 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:
  81. | Level | Tools | Description |
  82. |---|---|---|
  83. | **minimal** | 3 | Tasks, projects, workspaces only |
  84. | **essential** | 8 | Adds users, search, comments, schedules, statuses |
  85. | **complete** (default) | 10 | Full API access including custom fields and recurring tasks |
  86. | **custom** | varies | Pick exactly the tools you need |
  87. Custom example:
  88. ```bash
  89. MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npx motionmcp
  90. ```
  91. ## Tools Reference
  92. ### motion_tasks
  93. **Operations:** `create`, `list`, `list_all_uncompleted`, `get`, `update`, `delete`, `move`, `unassign`
  94. 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.
  95. `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.
  96. ```json
  97. {
  98. "operation": "create",
  99. "name": "Complete API integration",
  100. "workspaceName": "Development",
  101. "projectName": "Release Cycle Q2",
  102. "dueDate": "2025-06-15T09:00:00Z",
  103. "priority": "HIGH",
  104. "labels": ["api", "release"]
  105. }
  106. ```
  107. ### motion_projects
  108. **Operations:** `create`, `list`, `get`
  109. Manage Motion projects. Workspace and project names are fuzzy-matched, and the server auto-selects your "Personal" workspace if none is specified.
  110. ```json
  111. {"operation": "create", "name": "New Project", "workspaceName": "Personal"}
  112. ```
  113. ### motion_workspaces
  114. **Operations:** `list`, `get`
  115. List and inspect workspaces.
  116. ### motion_users
  117. **Operations:** `list`, `current`
  118. List users in a workspace or get the current authenticated user.
  119. ### motion_search
  120. **Operations:** `content`
  121. Search tasks and projects by query across a workspace.
  122. ```json
  123. {"operation": "content", "query": "API integration", "workspaceName": "Development"}
  124. ```
  125. ### motion_comments
  126. **Operations:** `list`, `create`
  127. Read and add comments on tasks and projects.
  128. ```json
  129. {"operation": "create", "taskId": "task_123", "content": "Updated the API endpoints as discussed"}
  130. ```
  131. ### motion_schedules
  132. **Operations:** `list`
  133. 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.
  134. ### motion_custom_fields
  135. **Operations:** `list`, `create`, `delete`, `add_to_project`, `remove_from_project`, `add_to_task`, `remove_from_task`
  136. Define and manage custom fields across workspaces, projects, and tasks.
  137. ```json
  138. {
  139. "operation": "create",
  140. "name": "Sprint",
  141. "type": "DROPDOWN",
  142. "options": ["Sprint 1", "Sprint 2", "Sprint 3"],
  143. "workspaceName": "Development"
  144. }
  145. ```
  146. ### motion_recurring_tasks
  147. **Operations:** `list`, `create`, `delete`
  148. Manage recurring task templates.
  149. ```json
  150. {
  151. "operation": "create",
  152. "name": "Weekly Team Standup",
  153. "recurrence": "WEEKLY",
  154. "projectName": "Team Meetings",
  155. "daysOfWeek": ["MONDAY", "WEDNESDAY", "FRIDAY"],
  156. "duration": 30
  157. }
  158. ```
  159. ### motion_statuses
  160. **Operations:** `list`
  161. List available statuses for a workspace.
  162. ## Advanced Configuration
  163. **Minimal setup (3 tools only):**
  164. ```json
  165. {
  166. "mcpServers": {
  167. "motion": {
  168. "command": "npx",
  169. "args": ["motionmcp"],
  170. "env": {
  171. "MOTION_API_KEY": "your_api_key",
  172. "MOTION_MCP_TOOLS": "minimal"
  173. }
  174. }
  175. }
  176. }
  177. ```
  178. **Custom tools selection:**
  179. ```json
  180. {
  181. "mcpServers": {
  182. "motion": {
  183. "command": "npx",
  184. "args": ["motionmcp"],
  185. "env": {
  186. "MOTION_API_KEY": "your_api_key",
  187. "MOTION_MCP_TOOLS": "custom:motion_tasks,motion_projects,motion_search"
  188. }
  189. }
  190. }
  191. }
  192. ```
  193. **Using your local workspace (npm):**
  194. ```json
  195. {
  196. "mcpServers": {
  197. "motion": {
  198. "command": "npm",
  199. "args": ["run", "mcp:dev"],
  200. "cwd": "/absolute/path/to/your/MotionMCP",
  201. "env": {
  202. "MOTION_API_KEY": "your_api_key"
  203. }
  204. }
  205. }
  206. }
  207. ```
  208. See the full developer setup in [DEVELOPER.md](./DEVELOPER.md).
  209. ## Debugging
  210. - Logs output to `stderr` in JSON format
  211. - Check for missing keys, workspace/project names, and permissions
  212. - Use `motion_workspaces` (list) and `motion_projects` (list) to validate IDs
  213. ```json
  214. {
  215. "level": "info",
  216. "msg": "Task created successfully",
  217. "method": "createTask",
  218. "taskId": "task_789",
  219. "workspace": "Development"
  220. }
  221. ```
  222. ## License
  223. Apache-2.0 License
  224. ---
  225. For more information, see the full [Motion API docs](https://docs.usemotion.com/) or [Model Context Protocol docs](https://modelcontextprotocol.io/docs/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.