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.

Without	With `fast_search` + `fast_apply`
Manual grep, misses related files	Ask naturally, get precise locations
Edits break imports elsewhere	Traces imports and call chains
Full rewrites burn tokens	Describe changes, no line numbers
Line number errors corrupt code	10,000+ tokens/sec merging

Features

Fast Apply — Apply code edits at 10,000+ tokens/sec via Relace API
Fast Search — Agentic codebase exploration with natural language queries
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)

Get your API key from Relace Dashboard, then add to your MCP client:

Cursor

~/.cursor/mcp.json

{
  "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 Code

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

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "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"
      }
    }
  }
}

VS Code

.vscode/mcp.json

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

Codex CLI

~/.codex/config.toml

[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

Variable	Required	Description
`RELACE_API_KEY`	✅	API key from Relace Dashboard
`RELACE_CLOUD_TOOLS`	❌	Set to `1` to enable cloud tools
`MCP_BASE_DIR`	❌	Project root (auto-detected via MCP Roots → Git → CWD)
`MCP_LOGGING`	❌	Set to `1` to enable file logging
`MCP_DOTENV_PATH`	❌	Path to `.env` file for centralized config

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

Tools

Core tools (fast_apply, fast_search) are always available. Cloud tools require RELACE_CLOUD_TOOLS=1.

For detailed parameters, see docs/tools.md.

Dashboard

Real-time terminal UI for monitoring operations.

pip install relace-mcp[tools]
relogs

For detailed usage, see docs/dashboard.md.

Platform Support

Platform	Status	Notes
Linux	✅ Fully supported	Primary development platform
macOS	✅ Fully supported	All features available
Windows	⚠️ Partial	`bash` tool unavailable; use WSL for full functionality

Troubleshooting

Error	Solution
`RELACE_API_KEY is not set`	Set the key in your environment or MCP config
`NEEDS_MORE_CONTEXT`	Include 1–3 anchor lines before/after target block
`FILE_TOO_LARGE`	File exceeds 1MB; split or increase limit
`ENCODING_ERROR`	Set `RELACE_DEFAULT_ENCODING` explicitly
`AUTH_ERROR`	Verify API key is valid and not expired
`RATE_LIMIT`	Too many requests; wait and retry

Development

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

License

MIT

relace-mcp