MCP Server for Propel

Submit git diffs for AI-powered code review directly from your IDE or terminal using the Propel code review platform.

Features

• Submit git diffs for async code review
• Automatically polls for results (reviews take 5-10 minutes)
• Retrieve detailed review comments with file paths, line numbers, and severity
• Quick status checks for in-progress reviews
• Works with Claude Desktop, Cursor, Claude Code, Codex, and Windsurf

Requirements

• Python 3.10 or higher (required by the MCP Python SDK)

Installation

Recommended: Using uvx (no install needed)

uvx runs the server in an isolated environment automatically — no virtual environment setup, no dependency conflicts.

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

No further installation steps needed. Configure your client to use uvx directly (see Setup below).

Alternative: Using pipx

pipx installs the server in its own isolated environment:

pipx install mcp-server-propel

Alternative: Using pip

Use a virtual environment to avoid conflicts with system packages:

python3 -m venv ~/.venvs/mcp-propel
source ~/.venvs/mcp-propel/bin/activate
pip install mcp-server-propel

Avoid installing with pip into your system Python. System-managed packages (like cffi) can cause install failures. A virtual environment, uvx, or pipx avoids this entirely.

Setup

Step 1: Get your API token

Get your Propel API token from Propel Settings. Your token needs reviews:write and reviews:read scopes.

Step 2: Configure your client

Choose the setup instructions for your tool:

• Claude Desktop
• Cursor
• Claude Code
• Codex CLI
• Windsurf

---

Claude Desktop

Config file location:

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

Using uvx (recommended):

{
  "mcpServers": {
    "propel": {
      "command": "uvx",
      "args": ["mcp-server-propel"],
      "env": {
        "PROPEL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Using a direct install (pipx or pip):

{
  "mcpServers": {
    "propel": {
      "command": "mcp-server-propel",
      "env": {
        "PROPEL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

---

Cursor

Config file location:

• Project-level: .cursor/mcp.json (in the project root)
• Global: ~/.cursor/mcp.json

You can also add it via Cursor Settings > Developer > MCP Tools > Add Custom MCP.

{
  "mcpServers": {
    "propel": {
      "command": "uvx",
      "args": ["mcp-server-propel"],
      "env": {
        "PROPEL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

---

Claude Code

Option A: CLI command (quickest)

claude mcp add --transport stdio \
  --env PROPEL_API_TOKEN=your-api-token-here \
  propel -- uvx mcp-server-propel

Add --scope project to share with your team, or --scope user to enable across all projects.

Option B: Project config file (.mcp.json in project root)

{
  "mcpServers": {
    "propel": {
      "command": "uvx",
      "args": ["mcp-server-propel"],
      "env": {
        "PROPEL_API_TOKEN": "${PROPEL_API_TOKEN}"
      }
    }
  }
}

With .mcp.json, you can use ${PROPEL_API_TOKEN} to reference your shell environment variable instead of hardcoding the token.

---

Codex CLI

Option A: CLI command

codex mcp add propel \
  --env PROPEL_API_TOKEN=your-api-token-here \
  -- uvx mcp-server-propel

Option B: Config file (~/.codex/config.toml or .codex/config.toml)

[mcp_servers.propel]
command = "uvx"
args = ["mcp-server-propel"]

[mcp_servers.propel.env]
PROPEL_API_TOKEN = "your-api-token-here"

---

Windsurf

Config file location:

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "propel": {
      "command": "uvx",
      "args": ["mcp-server-propel"],
      "env": {
        "PROPEL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

---

Tools

submit_review

Submit a git diff for code review. Returns immediately with a review ID, then instructs the AI to call get_review to poll for results.

Parameters:

• diff (required): Unified git diff output
• repository (required): Repository identifier (name, full name, or URL)
• base_commit (optional): Base commit SHA for additional context

get_review

Get review results. Polls the API automatically every 12 seconds until the review completes or fails (~12 min max).

Parameters:

• review_id (required): The review job identifier

check_review_status

Quick, non-polling status check. Returns only status and timing info without waiting.

Parameters:

• review_id (required): The review job identifier

Troubleshooting

"PROPEL_API_TOKEN environment variable is required"

• Ensure the token is set in your client's MCP config env section
• Restart your client after updating the config

"Invalid authorization token" / "Authorization token has expired"

• Generate a new token at Propel Settings
• Ensure it has reviews:write and reviews:read scopes

"Diff too large"

• Your diff exceeds the 1 MB size limit
• Try reviewing a smaller changeset (fewer files or commits)

"Repository not found"

• The repository must be connected to your Propel workspace
• Check the repository name matches what's configured in Propel

Cannot uninstall cffi or similar dependency conflicts

• This happens when installing with pip into system Python
• Fix: use uvx, pipx, or install inside a virtual environment (see Installation above)

Cursor not detecting tools

• Ensure you are on Cursor v2.4.21 or later
• Check that your PROPEL_API_TOKEN is set correctly in the config

Support

• Documentation: https://docs.propelcode.ai
• Issues: https://github.com/propel/mcp-server-propel/issues
• For development and contributing, see CONTRIBUTING.md