# MCP Server for Propel

Submit git diffs for AI-powered code review directly from your IDE or terminal using the [Propel](https://propelcode.ai) 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](https://github.com/modelcontextprotocol/python-sdk))

## Installation

### Recommended: Using `uvx` (no install needed)

[`uvx`](https://docs.astral.sh/uv/) runs the server in an isolated environment automatically — no virtual environment setup, no dependency conflicts.

```bash
# 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`](https://pipx.pypa.io/) installs the server in its own isolated environment:

```bash
pipx install mcp-server-propel
```

### Alternative: Using `pip`

Use a virtual environment to avoid conflicts with system packages:

```bash
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](https://app.propelcode.ai/administration/settings?tab=review-api-tokens). Your token needs `reviews:write` and `reviews:read` scopes.

### Step 2: Configure your client

Choose the setup instructions for your tool:

- [Claude Desktop](#claude-desktop)
- [Cursor](#cursor)
- [Claude Code](#claude-code)
- [Codex CLI](#codex-cli)
- [Windsurf](#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):**
```json
{
  "mcpServers": {
    "propel": {
      "command": "uvx",
      "args": ["mcp-server-propel"],
      "env": {
        "PROPEL_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

**Using a direct install (`pipx` or `pip`):**
```json
{
  "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**.

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

---

### Claude Code

**Option A: CLI command (quickest)**

```bash
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)**

```json
{
  "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**

```bash
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`)**

```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`

```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](https://app.propelcode.ai/administration/settings?tab=review-api-tokens)
- 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](CONTRIBUTING.md)
