Devin MCP Server

An MCP server that enables Claude Code to delegate implementation tasks to Devin.

Installation

Option 1: Install from Local Path (Development)

If you have the devin-mcp repository cloned locally:

# Navigate to the devin-mcp directory
cd /path/to/devin-mcp

# Install with uv (creates venv automatically)
uv pip install -e .

Option 2: Install from Git Repository

# Install directly from git (if repository is public)
uv pip install git+https://github.com/iainmck29/devin-mcp.git

# Or from a specific branch/tag
uv pip install git+https://github.com/iainmck29/devin-mcp.git@main

Option 3: Install as a Published Package

# If published to PyPI (future)
uv pip install devin-mcp

Note: The MCP server needs to be installed in a location where uv can find it. If installing from a local path, use an absolute path or ensure the path is accessible.

Configuration

Set your Devin API key and playbook ID as environment variables:

export DEVIN_API_KEY="your-api-key-here"
export DEVIN_PLAYBOOK_ID="your-playbook-id-here"

Usage

Running the Server

# Via module (using uv run to automatically use project venv)
uv run python -m devin_mcp.server

# Or via CLI entry point
uv run devin-mcp

Claude Code Configuration

Step 1: Get Your Devin API Key

1. Sign in to Devin
2. Navigate to your account settings or API section
3. Generate or copy your API key

Step 2: Locate Claude Code Settings File

The MCP settings file location depends on your OS:

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

Step 3: Configure the MCP Server

Open the settings file and add the devin server configuration. If the file doesn't exist or is empty, create it with this structure:

{
  "mcpServers": {
    "devin": {
      "command": "uv",
      "args": ["run", "python", "-m", "devin_mcp.server"],
      "env": {
        "DEVIN_API_KEY": "your-api-key-here",
        "DEVIN_PLAYBOOK_ID": "your-playbook-id-here"
      }
    }
  }
}

Important Notes:

• Replace "your-api-key-here" with your actual Devin API key
• Replace "your-playbook-id-here" with your Devin playbook ID
• If you installed from a local path, ensure uv is in your PATH
• The uv command must be able to find the installed devin_mcp package
• If you installed in a specific virtual environment, you may need to use the full path to uv or activate that environment

Step 4: Restart Claude Code

After saving the configuration file:

1. Completely quit Claude Code (not just close the window)
2. Reopen Claude Code
3. The MCP server should automatically start and connect

Step 5: Verify It's Working

1. Open Claude Code in any project
2. Check the MCP status indicator (usually in the bottom status bar)
3. Try asking Claude: "What MCP tools are available?" or "List the devin tools"
4. You should see the four Devin tools: devin_run_phase, devin_await_completion, devin_get_status, devin_send_message

Troubleshooting

Server won't start:

• Verify uv is installed: which uv or uv --version
• Check that devin_mcp is installed: uv run python -c "import devin_mcp; print('OK')"
• Check Claude Code logs for error messages

API key errors:

• Verify the API key is correct in the config file
• Ensure there are no extra quotes or whitespace around the key
• Test the API key manually: export DEVIN_API_KEY="your-key" && uv run python -c "from devin_mcp.client import DevinClient; print('OK')"

Tools not appearing:

• Restart Claude Code completely
• Check the MCP connection status in Claude Code
• Verify the config JSON is valid (no trailing commas, proper quotes)

Available Tools

devin_run_phase

Create a new Devin session with a playbook and prompt.

Parameters:

• prompt (string, required): The task prompt
• playbook_id (string, optional): The Devin playbook ID. Uses DEVIN_PLAYBOOK_ID env var if not provided.

Returns: { success, session_id, url } or { success: false, error }

devin_await_completion

Poll a session until it reaches a terminal state.

Parameters:

• session_id (string, required): The session to monitor
• timeout (integer, optional): Max wait in seconds (default: 600)

Returns: Full session details or raises DevinTimeoutError

devin_get_status

Quick, non-blocking status check.

Parameters:

• session_id (string, required): The session to check

Returns: { success, session_id, url, status_enum } or { success: false, error }

devin_send_message

Send a follow-up message to a session.

Parameters:

• session_id (string, required): The session to message
• message (string, required): The message content

Returns: { success, detail } or { success: false, error }

Example Workflow

# 1. Start a phase (uses DEVIN_PLAYBOOK_ID from environment)
result = devin_run_phase(
    prompt="thoughts/shared/plans/2024-01-15-auth.md, phase 1, branch feature/auth"
)
# Or override with a specific playbook:
# result = devin_run_phase(prompt="...", playbook_id="pb_abc123")
session_id = result["session_id"]

# 2. Wait for completion
session = devin_await_completion(session_id, timeout=600)

# 3. Check result
if session["status_enum"] == "finished":
    print("Phase completed successfully!")
elif session["status_enum"] == "blocked":
    # Send clarification if needed
    devin_send_message(session_id, "Use the existing User model from src/models/user.py")

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests (using uv run to ensure correct environment)
uv run pytest

# Type check
uv run mypy src/