English | 简体中文

Unofficial Relace MCP Server

Unofficial — Personal project, not affiliated with Relace.

Built with AI — Developed entirely with AI assistance (Antigravity, Codex, Cursor, Github Copilot, Windsurf).

MCP server providing AI-powered code editing and intelligent codebase exploration tools.

Features

• Fast Apply — Apply code edits at 10,000+ tokens/sec via Relace API
• Agentic Search — Agentic codebase exploration with natural language queries (fast_search is deprecated alias, removed in 0.2.5)
• Agentic Retrieval — Two-stage semantic + agentic code retrieval (requires RELACE_CLOUD_TOOLS=1 and MCP_SEARCH_MODE=indexed or both)
• Cloud Sync — Upload local codebase to Relace Cloud for semantic search
• Cloud Search — Semantic code search over cloud-synced repositories
• Dashboard — Real-time terminal UI for monitoring operations

Quick Start

Prerequisites: uv, git, ripgrep (recommended)

Using Relace (default) or RELACE_CLOUD_TOOLS=1: get your API key from Relace Dashboard, then add to your MCP client:

{
  "mcpServers": {
    "relace": {
      "command": "uv",
      "args": ["tool", "run", "relace-mcp"],
      "env": {
        "RELACE_API_KEY": "rlc-your-api-key",
        "MCP_BASE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

claude mcp add relace \
  --env RELACE_API_KEY=rlc-your-api-key \
  --env MCP_BASE_DIR=/absolute/path/to/your/project \
  -- uv tool run relace-mcp

{
  "mcpServers": {
    "relace": {
      "command": "uv",
      "args": ["tool", "run", "relace-mcp"],
      "env": {
        "RELACE_API_KEY": "rlc-your-api-key",
        "MCP_BASE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "relace": {
        "type": "stdio",
        "command": "uv",
        "args": ["tool", "run", "relace-mcp"],
        "env": {
          "RELACE_API_KEY": "rlc-your-api-key",
          "MCP_BASE_DIR": "${workspaceFolder}"
        }
      }
    }
  }
}

[mcp_servers.relace]
command = "uv"
args = ["tool", "run", "relace-mcp"]

[mcp_servers.relace.env]
RELACE_API_KEY = "rlc-your-api-key"
MCP_BASE_DIR = "/absolute/path/to/your/project"

Configuration

* Optional if both: (1) APPLY_PROVIDER and SEARCH_PROVIDER are non-Relace providers, and (2) RELACE_CLOUD_TOOLS=false.

For .env usage, encoding settings, custom LLM providers, and more, see docs/advanced.md.

Tools

Core tools (fast_apply, agentic_search) are always available. fast_search is a deprecated alias for agentic_search (removed in 0.2.5). Cloud tools require RELACE_CLOUD_TOOLS=1. agentic_retrieval requires both RELACE_CLOUD_TOOLS=1 and MCP_SEARCH_MODE=indexed or both.

For detailed parameters, see docs/tools.md.

Language Support

LSP tools use external language servers installed on your system.

Dashboard

Real-time terminal UI for monitoring operations.

pip install relace-mcp[tools]
relogs

For detailed usage, see docs/dashboard.md.

Benchmark

Evaluate agentic_search performance using the Loc-Bench code localization dataset.

# Install benchmark dependencies
pip install relace-mcp[benchmark]

# Build dataset from Hugging Face
uv run python -m benchmark.cli.build_locbench --output artifacts/data/raw/locbench_v1.jsonl

# Run evaluation
uv run python -m benchmark.cli.run --dataset artifacts/data/raw/locbench_v1.jsonl --limit 20

For grid search, analysis tools, and metrics interpretation, see docs/benchmark.md.

Platform Support

Troubleshooting

Development

git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra dev
uv run pytest

License

MIT