Skip to content

DEVELOPER.md

Latest commit

 

History

History
185 lines (136 loc) · 5.76 KB

DEVELOPER.md

File metadata and controls

185 lines (136 loc) · 5.76 KB

Developer Guide — Motion MCP Server

This guide is for contributors and anyone running Motion MCP locally from source.

Prerequisites

Get the code and install

# clone or open your local copy
# (replace the URL with your fork if contributing)
 git clone https://github.com/devondragon/MotionMCP.git
 cd MotionMCP

# install dependencies
 npm install

# copy environment template and edit values
 cp .env.example .env
 # open .env and set MOTION_API_KEY

Important environment variables:

  • MOTION_API_KEY: required for all requests
  • MOTION_MCP_TOOLS: optional; controls which tool set is exposed (see below)

Run locally

You can run in TypeScript dev mode (fast iteration) or build and run the compiled JS.

  • Dev mode (ts-node):
npm run mcp:dev
  • Build, then run compiled:
npm run build
npm run mcp

Both commands start the MCP server on stdio (no HTTP port). Clients like Claude Desktop will launch it and communicate over stdio.

Tool configuration (optional)

Set MOTION_MCP_TOOLS in your environment (for example in .env) to control the exposed tools:

  • minimal — core consolidated tools only: motion_tasks, motion_projects, motion_workspaces
  • essential (default) — consolidated tools plus commonly-used endpoints and helpers
  • complete — all consolidated tools
  • custom:tool1,tool2 — specify exactly which tools to enable

Examples:

# Only core consolidated tools
MOTION_MCP_TOOLS=minimal npm run mcp:dev

# Default set (explicit)
MOTION_MCP_TOOLS=essential npm run mcp

# Custom selection
MOTION_MCP_TOOLS=custom:motion_tasks,motion_projects,motion_search npm run mcp:dev

Claude Desktop configuration

To use your local build with Claude Desktop, add an entry to your Claude Desktop config. Recommended approach is direct node execution for maximum reliability.

  • macOS config file path: ~/Library/Application Support/Claude/claude_desktop_config.json

Recommended (direct node execution):

{
  "mcpServers": {
    "motion": {
      "command": "node",
      "args": ["/absolute/path/to/your/MotionMCP/dist/mcp-server.js"],
      "env": {
        "MOTION_API_KEY": "your_api_key",
        "MOTION_MCP_TOOLS": "essential"
      }
    }
  }
}

Alternative (npm - may have working directory issues):

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

Setup steps:

  1. Build the project: npm run build
  2. Make the server executable: chmod +x dist/mcp-server.js
  3. Use absolute paths in your Claude Desktop config
  4. Restart Claude Desktop after config changes

Notes:

  • The server communicates over stdio. There is no HTTP port to configure.
  • Direct node execution is more reliable than npm in Claude Desktop's environment.
  • Remember to rebuild (npm run build) after making code changes.

Cloudflare Worker (remote MCP server)

The project also includes a Cloudflare Worker entry point (src/worker.ts) that exposes the same MCP tools over HTTP. This enables access from Claude mobile/web and ChatGPT — any client that supports remote MCP servers via Streamable HTTP or SSE.

Prerequisites

Local development

npm run worker:dev
# Starts at http://localhost:8787
# Uses MOTION_API_KEY from your .env file
# Test: curl http://localhost:8787/health

The local dev server reads MOTION_MCP_SECRET from .env (or skips validation if not set). Set it to a test value like test-secret for local testing.

Deploy to Cloudflare

# Set secrets (prompted for values)
npx wrangler secret put MOTION_API_KEY
npx wrangler secret put MOTION_MCP_SECRET  # generate with: 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 clients

  • Claude (web/mobile): Add the URL in claude.ai > Settings > Connectors. Syncs to mobile automatically.
  • ChatGPT (web/mobile): Add the URL in Settings > Connectors.

Worker type checking

The Worker uses a separate TypeScript config (tsconfig.worker.json) with ES modules and Workers types:

npm run worker:type-check

This is separate from the main npm run type-check / npm run build which compiles the stdio server.

Architecture notes

  • The Worker reuses all existing handlers, services, tools, and utilities — it only differs in transport
  • McpAgent from the Cloudflare Agents SDK handles Streamable HTTP and SSE via Durable Objects
  • MotionApiService receives the API key from Worker env bindings instead of process.env
  • Tool JSON Schemas are converted to Zod schemas at init time (via src/utils/jsonSchemaToZod.ts) because McpServer.tool() requires Zod
  • Access is controlled by a secret token in the URL path — treat the full URL like a password

Troubleshooting

  • Missing or invalid API key: verify MOTION_API_KEY is set (in your shell or .env).
  • Typescript errors: run npm run type-check and fix issues before building. For Worker issues, also run npm run worker:type-check.
  • No tools listed in client: check MOTION_MCP_TOOLS and that the client launched the expected script (mcp vs mcp:dev).
  • Worker 404 on all requests: verify MOTION_MCP_SECRET is set and matches the secret in your URL path.
  • Worker local dev issues: make sure MOTION_API_KEY is in your .env file.

Happy hacking! If you run into issues, open an issue or PR on GitHub.