Click on "Install 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., "@Motion MCP Servercreate task: Review budget, due Friday, high priority"
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.
Motion MCP Server
Connect AI assistants to Motion for task and project management.
Installation
npm install -g @h3ro-dev/motion-mcp-serverQuick Setup
1. Get Motion API Key
Motion → Settings → API & Integrations → Create New API Key
2. Configure
{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}Config location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}{
"mcpServers": {
"motion": {
"command": "npx",
"args": ["-y", "@h3ro-dev/motion-mcp-server"],
"env": {
"MOTION_API_KEY": "your-api-key"
}
}
}
}3. Restart your AI assistant
Features
✅ All Motion APIs - Tasks, projects, workspaces, users, comments, recurring tasks, schedules
🚦 Smart Rate Limiting - Automatic handling of Motion's 12 req/3min limit
💾 Persistent State - SQLite database maintains rate limits across restarts
🔍 Clear Errors - Helpful messages for debugging
📝 Full TypeScript - Type-safe and reliable
Usage Examples
"List my tasks"
"Create task: Review budget, due Friday, high priority"
"Move task abc123 to Marketing workspace"
"Add comment to task xyz789: Waiting for approval"
"Create recurring task: Daily standup at 9am"Tools Reference
Tool | Description | Example |
| List tasks with filters |
|
| Get task details |
|
| Create new task |
|
| Update task |
|
| Delete task |
|
| Move to workspace |
|
| Remove assignee |
|
Tool | Description | Example |
| List projects |
|
| Get project details |
|
| Create project |
|
| Update project |
|
| Archive project |
|
Tool | Description |
| List all workspaces |
| Get workspace details |
| List workspace users |
| Get current user |
| List task comments |
| Add task comment |
| List recurring tasks |
| Create recurring task |
| Delete recurring task |
| List schedules |
Configuration
Variable | Required | Default | Description |
| ✅ | - | Your Motion API key |
| ❌ |
| API endpoint |
| ❌ |
| Rate limit window (3 min) |
| ❌ |
| Max requests per window |
| ❌ |
| SQLite database path |
| ❌ |
| Enable debug logging |
Development
# Clone
git clone https://github.com/h3ro-dev/motion-mcp-server.git
cd motion-mcp-server
# Install
npm install
# Build
npm run build
# Test
npm test
# Run locally
MOTION_API_KEY=your-key npm startTroubleshooting
"Invalid API Key"
Check API key is correct
Ensure no extra spaces
Regenerate key if needed
"Rate limit exceeded"
Server automatically handles this
Wait time shown in error
Check
DATABASE_PATHis writable
"Task not found"
Verify task ID exists
Check workspace access
Task may be archived
License
MIT © h3ro-dev
Links
This server cannot be installed
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.