Identityex/use-motion-mcp-server

Motion MCP Server

A production-ready MCP (Model Context Protocol) Server that integrates with Motion (usemotion.com) task management platform. This server enables AI assistants to manage projects and tasks through Motion's API while maintaining local context in .claude/motion/ directory using markdown files.

Features

🎯 Core Functionality

• Full Motion API Integration: Projects, tasks, workspaces, users, comments
• Local Storage: Markdown-based task files with YAML frontmatter
• Bidirectional Sync: Keep local and remote data in sync with conflict resolution
• Rate Limited: Respects Motion's API limits (12/min individual, 120/min team)

🤖 AI-Powered Features

• Task Enrichment: AI-enhanced descriptions and acceptance criteria
• Goal Breakdown: Convert high-level goals into actionable task lists
• Workflow Planning: Generate comprehensive project plans
• Status Reports: Automated progress summaries

📁 MCP Resources

• Project Overviews: Real-time project status and metrics
• Task Files: Individual task details as markdown resources
• Documentation: Project docs accessible through MCP
• AI Prompts: Templates for task planning and reporting

Installation

Prerequisites

• Node.js 18+ and npm
• Motion account with API key
• Claude Desktop (for MCP integration)

Setup

1. Clone and Install

git clone https://github.com/idxstudios/use-motion-mcp-server.git
cd use-motion-mcp-server
npm install

2. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env with your Motion API key
MOTION_API_KEY=your_motion_api_key_here
MOTION_IS_TEAM_ACCOUNT=false  # true for team accounts

3. Build the Server

# Generate OpenAPI routes first (required for first build)
make openapi

# Full build with OpenAPI generation + TypeScript compilation
make build

# OR for TypeScript compilation only (after OpenAPI generated)
npm run build

4. Configure Claude Desktop Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "motion": {
      "command": "node",
      "args": ["/absolute/path/to/motion-mcp-server/dist/server/index.js"],
      "env": {
        "MOTION_API_KEY": "your-motion-api-key"
      }
    }
  }
}

Architecture

The server follows a Domain Controllers → App (Commands/Queries) → Services pattern with Functional/Reactive Programming (FRP) principles:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│Domain Controllers│───▶│   App Layer     │───▶│    Services     │
│  (MCP Handlers) │    │ Commands/Queries│    │ Motion/Storage  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🗂️ Directory Structure

src/
├── api/mcp/v1-routes/     # Generated OpenAPI code
│   ├── models/            # Generated TypeScript interfaces
│   ├── routes/            # Generated controller interfaces
│   └── tools.ts           # Generated MCP tool schemas
├── api/mcp/v1-controllers/# Domain controller implementations
│   ├── project-controller.ts
│   ├── task-controller.ts
│   ├── workflow-controller.ts
│   ├── sync-controller.ts
│   ├── context-controller.ts
│   └── docs-controller.ts
├── app/                   # Business logic layer
│   ├── motion/            # Motion API commands & queries
│   ├── projects/          # Project commands & queries
│   ├── tasks/             # Task commands & queries
│   ├── workflow/          # Workflow planning
│   ├── sync/              # Synchronization logic
│   ├── context/           # Context management
│   └── docs/              # Documentation generation
├── services/              # External service integrations
│   ├── motion-service.ts  # Motion API client
│   ├── storage/           # Local file management
│   └── ai/                # AI enhancements
├── setup/                 # Configuration and DI
│   └── dependencies.ts    # Dependency injection
└── server/index.ts        # MCP server entry point

🔧 OpenAPI-Based Code Generation

Tools and interfaces are generated from YAML schemas:

• Define tools in schemas/mcp/v1/mcp-tools.yaml
• Custom Handlebars templates in schemas/api-gen/server/
• Generated code in src/api/mcp/v1-routes/
• Run make openapi to regenerate

Available Tools

📋 Project Management

• motion.project.list - List all projects with pagination
• motion.project.create - Create new projects
• motion.project.bind - Bind project to local storage
• motion.project.sync - Sync project with Motion

✅ Task Operations

• motion.task.create - Create tasks (with AI enrichment)
• motion.task.list - List and filter tasks
• motion.task.search - Search tasks in local storage
• motion.task.update - Update task properties
• motion.task.complete - Mark tasks as completed

🤖 AI Features

• motion.task.enrich - AI-enhance task descriptions
• motion.task.batch_create - Create multiple tasks from goals
• motion.task.analyze - Analyze task complexity
• motion.workflow.plan - Generate comprehensive plans

🔄 Sync & Context

• motion.sync.all - Sync all bound projects
• motion.sync.check - Check sync status
• motion.context.save - Save project context for AI
• motion.context.load - Load project context

📄 Documentation

• motion.docs.create - Generate project documentation
• motion.docs.update - Update existing docs
• motion.status.report - Generate status reports

🏢 Workspace Management

• motion.workspace.list - List all available workspaces
• motion.workspace.set_default - Set default workspace for new projects
• motion.workspace.get_settings - Get workspace-specific settings
• motion.workspace.update_settings - Update workspace preferences

Local Storage Structure

The server maintains local context in .claude/motion/:

.claude/motion/
├── workspace-settings/
│   ├── default.json      # Default workspace configuration
│   └── [workspace-id].json # Workspace-specific settings
└── [project-id]/
    ├── meta.json         # Project metadata
    ├── tasks/
    │   └── [task-id].md  # Task files with YAML frontmatter
    └── docs/
        └── *.md          # Project documentation

Task File Format

---
id: task_123
projectId: proj_456
status: In Progress
priority: HIGH
duration: 120
# ... other metadata
---

# Task Title

## Description
Detailed task description...

## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2

Workspace Settings Format

{
  "workspaceId": "workspace_123",
  "defaultProjectId": "project_456",
  "defaultPriority": "MEDIUM",
  "defaultDuration": 60,
  "aiProvider": "openai"
}

Development

🛠️ Build Commands (Make)

make help          # Show all available commands
make install       # Install dependencies
make build         # Build the project
make test          # Run tests
make lint          # Run linter
make dev           # Start development server
make check         # Run all quality checks
make docker-build  # Build Docker image

🔍 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test files
npm test -- --testPathPattern=tasks

📊 Monitoring

The server includes comprehensive error handling and logging:

• Request/response logging
• Rate limit monitoring
• Sync conflict detection
• Validation error reporting

Docker Deployment

Build and Run

# Build image
make docker-build

# Run container
docker run -it --rm \
  -v "${PWD}/.claude:/app/.claude" \
  -e MOTION_API_KEY="your-api-key" \
  motion-mcp-server

Docker Compose

version: '3.8'
services:
  motion-mcp:
    build: .
    volumes:
      - ./.claude:/app/.claude
    environment:
      - MOTION_API_KEY=${MOTION_API_KEY}
      - MOTION_IS_TEAM_ACCOUNT=false

Configuration

Environment Variables

MOTION_API_KEY=              # Required: Your Motion API key
MOTION_IS_TEAM_ACCOUNT=      # Rate limit configuration
MOTION_BASE_URL=             # Motion API base URL
REQUEST_TIMEOUT=             # API request timeout (ms)
CLAUDE_DATA_DIR=             # Local storage directory
LOG_LEVEL=                   # Logging verbosity

Rate Limiting

The server automatically detects account type and applies appropriate limits:

• Individual accounts: 12 requests/minute
• Team accounts: 120 requests/minute

Troubleshooting

Common Issues

❌ "Motion API key not found"

# Check environment variables
echo $MOTION_API_KEY

# Verify .env file
cat .env

❌ "Project not bound locally"

# First bind the project
# Use motion.project.bind tool in Claude

❌ Rate limit exceeded

# Check if team account flag is correct
MOTION_IS_TEAM_ACCOUNT=true  # For team accounts

Debug Mode

# Enable debug logging
export LOG_LEVEL=debug
npm start

API Reference

The server implements all major Motion API endpoints:

• Projects API
• Tasks API
• Workspaces API
• Users API
• Comments API

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run quality checks: make check
6. Submit a pull request

Code Style

• TypeScript with strict mode
• Functional/Reactive Programming patterns
• Immutable data structures
• Pure functions without side effects

License

MIT License - see LICENSE file for details.

Support

• 📚 Motion API Documentation
• 🔧 MCP Specification
• 🐛 Report Issues

Built with ❤️ for the Claude ecosystem