Motion Mcp Server

Motion MCP Server

An open-source MCP server enabling AI assistants to interact with the Motion API for intelligent task and project management.

Table of Contents

• [Motivation](#motivation)
• [Features](#features)
• [Smart Data Retrieval for AI Efficiency](#smart-data-retrieval-for-ai-efficiency)
• [About Motion Task Management](#about-motion-task-management)
• [Setup](#setup)
• [Usage with Claude Desktop](#usage-with-claude-desktop)
• [Usage with SSE/HTTP Clients via MCP Proxy](#usage-with-ssehttp-clients-via-mcp-proxy)
• [Other Ways to Connect AI to Motion](#other-ways-to-connect-ai-to-motion)
• [Rate Limiting](#rate-limiting)
• [Understanding Rate Limit Errors](#understanding-rate-limit-errors)
• [Credits and Acknowledgements](#credits-and-acknowledgements)
• [Troubleshooting](#troubleshooting)
• [Contributing](#contributing)
• [License](#license)

Motivation

The primary motivation behind creating this Motion MCP Server was to seamlessly integrate powerful AI assistants (like Claude Desktop, Cursor, and others) with the robust task and project management capabilities of Motion (https://www.usemotion.com/). By exposing Motion's API through MCP tools, users can manage their tasks, projects, and schedules using natural language by communicating with their preferred AI assistant. This bridges the gap between conversational AI and structured personal/team productivity, aiming for a more intuitive and efficient workflow.

Features

• MCP tools for various Motion API endpoints (projects, tasks, users, etc.).
• Automatic rate limiting to prevent exceeding Motion API quotas (12 calls per 3 minutes).
• Persistent state for rate limiting across server restarts, using a local SQLite database.

Smart Data Retrieval for AI Efficiency

This MCP server is engineered with AI assistants in mind, particularly concerning the volume and relevance of data exchanged. Interacting with APIs can often result in verbose responses, flooding an AI's context window with information that might not be immediately useful. To address this, the server incorporates several strategies for token efficiency:

• Sensible Defaults: For most tools that retrieve data (like fetching tasks or projects), the server returns a curated set of default fields. These defaults are chosen to provide the most commonly useful information at a glance, ensuring you get key details without unnecessary clutter.

• User-Controlled Specificity: While defaults are helpful, you're always in control. If you need more (or different) information, you can instruct your AI assistant to request specific fields from the Motion API. This can range from asking for a few additional details to requesting the complete data set for a particular item. This flexibility ensures you get exactly what you need, when you need it.

• Intelligent Handling of Complex Data: The server employs smart processing for complex data structures, like lists of items or nested information. For instance:
• When you ask for a list of task assignees, it might, by default, return just their names for brevity.
• Dates are often automatically formatted into a consistent, human-readable YYYY-MM-DD format.
• Information within nested objects (like a project manager's details) can be accessed directly (e.g., manager.name) or simplified by default.

The overarching goal is to strike a balance: deliver rich, informative data from your Motion workspace while respecting the operational constraints of AI assistants. This makes interactions smoother, faster, and more focused on the information that truly matters for your workflow.

About Motion Task Management

Motion (https://www.usemotion.com/) is an AI-powered platform designed to unify and automate task management, project planning, and calendar scheduling. Key aspects relevant to this MCP server include:

• AI Task & Calendar Planning: Motion uses AI to automatically schedule tasks onto your calendar, considering priorities, deadlines, dependencies, and available time. It dynamically adjusts your schedule as new items arise or plans change.
• Intelligent Prioritization: The platform helps identify and focus on the most urgent and important tasks, aiming to prevent missed deadlines by proactively flagging at-risk items.
• Unified Workspace: It consolidates projects, tasks, and calendars, often integrating with other tools like email and messaging apps to centralize your work.

This MCP server allows AI assistants to tap into these capabilities, enabling users to interact with their Motion tasks and schedules through natural language.

Setup

Follow these steps to set up and run the Motion MCP Server:

1. Clone the repository:

``bash git clone # Replace with the actual URL cd motion_mcp_server ``

1. Node.js Version (Crucial for better-sqlite3):

This project uses better-sqlite3, a native Node.js module. Native modules are compiled against a specific Node.js Application Binary Interface (ABI) version, identified by NODE_MODULE_VERSION.

• Problem: If you install dependencies (npm install) with one Node.js version (e.g., v21.x, NODE_MODULE_VERSION 120) and then try to run the server with an MCP client that uses a different, ABI-incompatible Node.js version (e.g., Claude Desktop often uses Node.js v18.x, NODE_MODULE_VERSION 108), you will encounter an ERR_DLOPEN_FAILED error. The error message will typically state that the module "was compiled against a different Node.js version".
• Solution:
• Identify the Node.js version used by your MCP client. For example, Claude Desktop logs usually show the Node.js version it's using (e.g., "Node.js v18.19.0"). For Cursor, Node.js v21.1.0 has been found to work correctly with this MCP server (as of May 2024).
• Use a Node.js version manager (like nvm or nvs) to install and switch to that same Node.js version in your local terminal before proceeding to the next step.

```bash # Example using nvm if Claude Desktop uses Node v18.19.0 nvm install 18.19.0 nvm use 18.19.0

# Example using nvm if Cursor is the target client (and v21.1.0 is desired) nvm install 21.1.0 nvm use 21.1.0 ```

• If you don't know the client's Node.js version, Node.js LTS versions (e.g., v18.x, v20.x) are generally good choices for broader compatibility. However, for this specific server and client combination, targeting the known compatible version is best.

1. Install dependencies:

Once your terminal is using the correct Node.js version, install the dependencies: ``bash npm install ` This step installs better-sqlite3 and compiles it for your active Node.js version. **Important:** If you later switch Node.js versions locally for other projects, you might need to rebuild better-sqlite3 for this project to work with the MCP client again. You can do this by running npm rebuild better-sqlite3 --update-binary or removing node_modules and running npm install` again while on the correct Node.js version.

1. Configure API Key:

The server expects the Motion API key to be available as an environment variable named MOTION_API_KEY.

• For MCP Clients (like Claude Desktop, Cursor): Configure this in the client's MCP server settings. See the "Usage with Claude Desktop" section for an example.
• For local shell execution (testing/development):

``bash export MOTION_API_KEY="your_motion_api_key_here" ` Replace "yourmotionapikeyhere"` with your actual Motion API key.

1. Starting the Server:

The server is typically started automatically by an MCP client when you invoke one of its tools.

• For local development/testing with npx tsx (recommended):

If you want to run the server directly (e.g., for use with MCP Inspector), ensure you are in the project root and your active Node.js version matches the one used for npm install. ``bash npx tsx main.ts ` tsx is a utility that executes TypeScript files directly. If you haven't used it before, you might need to install it or use ts-node`.

• Using npm start (if configured):

If your package.json has a start script like "start": "tsx main.ts", you can use: ``bash npm start ``

### Debugging with MCP Inspector

The @modelcontextprotocol/inspector is a valuable tool for testing and debugging MCP servers locally. It allows you to see the communication between a client (like the Inspector's web UI) and your MCP server.

1. Ensure your server is configured in an MCP client config file (Recommended):

The easiest way to use the Inspector is by pointing it to an existing MCP client configuration file where your motion server is already defined (as described in the "Usage with Claude Desktop" section). For example, using your Claude Desktop config: ``bash npx @modelcontextprotocol/inspector --config "/path/to/your/Claude/claude_desktop_config.json" --server motion ``

• Replace "/path/to/your/Claude/claude_desktop_config.json" with the actual path to your Claude Desktop configuration file.
• The --server motion flag tells the Inspector to specifically proxy the server named "motion" from that config file.

1. Using MCP Inspector without a full config file (Alternative):

While possible, it's more complex as you'd need to provide all server parameters (command, args, env vars) directly to the Inspector via command-line arguments. Using the --config and --server flags as shown above is simpler if you already have the server defined for a client like Claude Desktop.

1. Accessing the Inspector:

Once started, the MCP Inspector will output a URL (usually http://127.0.0.1:6274) that you can open in your web browser. From there, you can select your "motion" server, view its available tools, and make calls to test its responses and behavior, including rate limiting.

Important for Inspector Usage:

• Ensure that the Node.js version active in your terminal when you run npm install (for better-sqlite3) is the same one that MCP Inspector will use to launch your server. If MCP Inspector uses a different system Node.js, you might encounter the NODE_MODULE_VERSION mismatch. You can often see the command Inspector uses to launch your server in its startup logs.
• The MOTION_API_KEY must be correctly set in the env section of your server definition within the claude_desktop_config.json for the Inspector to pass it to your server.

Usage with Claude Desktop

To use this Motion MCP server with Claude Desktop:

1. Locate your Claude Desktop configuration file. This is typically found at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

1. Edit the claude_desktop_config.json file. Add or update the mcpServers section to include an entry for the "motion" server.

Important:

• Replace "/path/to/your/motion_mcp_server/main.ts" with the absolute path to the main.ts file in your cloned repository.
• Replace "YOUR_MOTION_API_KEY_HERE" with your actual Motion API key.

``json { "mcpServers": { "motion": { "command": "npx", "args": [ "tsx", "/path/to/your/motion_mcp_server/main.ts" // <-- IMPORTANT: Change this path ], "env": { "MOTION_API_KEY": "YOUR_MOTION_API_KEY_HERE" // <-- IMPORTANT: Change this key } } } } ``

1. Restart Claude Desktop. After saving the configuration file, you must fully quit and restart Claude Desktop for the changes to take effect.

Once configured and restarted, Claude should be able to invoke the Motion tools (e.g., "motion get_tasks").

Usage with SSE/HTTP Clients via MCP Proxy

Some AI clients and applications only support Server-Sent Events (SSE) or streamable HTTP connections rather than the standard MCP stdio protocol. For these clients, you can use the mcp-proxy server to bridge the connection between your HTTP/SSE client and this Motion MCP server.

Prerequisites

Before proceeding, ensure you have completed the basic [Setup](#setup) steps for this Motion MCP server, including:

• Installing Node.js and dependencies
• Configuring your MOTION_API_KEY

Installing MCP Proxy

The mcp-proxy server acts as a bridge, converting HTTP/SSE requests into MCP stdio communication with this Motion server.

1. Install mcp-proxy using uv:

``bash uv tool install git+https://github.com/sparfenyuk/mcp-proxy ``

1. Verify installation and locate the binary:

For less technical users, you can find the installation path using: ``bash which mcp-proxy ` This will output the full path to the mcp-proxy binary (e.g., /home/user/.local/bin/mcp-proxy`).

Starting the MCP Proxy Server

Start the proxy server with your Motion API key and the path to this server's main.ts file:

/path/to/mcp-proxy --port 8080 --env MOTION_API_KEY "your_motion_api_key_here" npx tsx /path/to/your/motion_mcp_server/main.ts

Important replacements:

• Replace /path/to/mcp-proxy with the actual path from the which mcp-proxy command
• Replace "your_motion_api_key_here" with your actual Motion API key
• Replace /path/to/your/motion_mcp_server/main.ts with the absolute path to this server's main.ts file

Example:

/home/user/.local/bin/mcp-proxy --port 8080 --env MOTION_API_KEY "mt_abc123xyz789" npx tsx /home/user/projects/motion-mcp-server/main.ts

Configuring Your MCP Client

Once the proxy server is running, configure your MCP client depending on the connection type it supports:

For Streamable HTTP Connections

Add this configuration to your client's MCP configuration file:

{
  "mcpServers": {
    "motion-mcp": {
      "type": "mcp",
      "url": "http://localhost:8080/mcp",
      "note": "Motion MCP server via HTTP proxy"
    }
  }
}

For SSE (Server-Sent Events) Connections

Add this configuration to your client's MCP configuration file:

{
  "mcpServers": {
    "motion-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "note": "Motion MCP server via SSE proxy"
    }
  }
}

Testing with MCP Inspector

You can test your proxy setup using the MCP Inspector tool:

1. Create a test configuration file (e.g., mcp-test-config.json) with one of the configurations above.

1. Run the Inspector:

``bash npx @modelcontextprotocol/inspector --config /path/to/mcp-test-config.json --server motion-mcp ` (Use --server motion-sse` if you're testing the SSE configuration)

1. Access the Inspector: Open the URL provided by the Inspector (typically http://127.0.0.1:6274) in your web browser to test the Motion tools through the proxy.

Important Notes

• Keep the proxy running: The mcp-proxy server must remain running while your client is using the Motion MCP server. If you stop the proxy, your client will lose connection to the Motion tools.

• Port conflicts: If port 8080 is already in use, choose a different port (e.g., --port 8081) and update your client configuration URLs accordingly.

• Rate limiting: The same rate limiting rules apply when using the proxy. The Motion API's 12 calls per 3-minute limit is enforced regardless of the connection method.

• Security: The proxy server runs locally and exposes HTTP endpoints. Ensure your firewall settings are appropriate for your securi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: christopher-czaban
• Source: christopher-czaban/motion-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.