Relace MCP
Unofficial Relace MCP client with AI features. Personal project; not affiliated with or endorsed by Relace
Installation
npx relace-mcpAsk AI about Relace MCP
Powered by Claude ยท Grounded in docs
I know everything about Relace MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
| Without | With agentic_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
- Agentic Search โ Agentic codebase exploration with natural language queries
- Agentic Retrieval โ Hybrid semantic hints + live code exploration, with stale-hint support and explicit cloud maintenance (enable with
MCP_SEARCH_RETRIEVAL=1; choose the backend withMCP_RETRIEVAL_BACKEND) - Cloud Search โ Semantic code search over cloud-synced repositories
Quick Start
Prerequisites: uv, git, ripgrep (recommended)
Using the relace backend (default): 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; required for Relace providers and cloud tools |
MCP_SEARCH_RETRIEVAL | โ | Set to 1 to register the agentic_retrieval tool |
MCP_RETRIEVAL_BACKEND | โ | Semantic retrieval backend: relace (default), codanna, chunkhound, or none |
MCP_RETRIEVAL_HINT_POLICY | โ | Retrieval hint policy: prefer-stale (default) or strict |
MCP_BACKGROUND_INDEX_MONITOR | โ | Opt-in periodic refresh monitor for local indexes; requires a pinned MCP_BASE_DIR and a local backend |
MCP_BACKGROUND_INDEX_INTERVAL_SECONDS | โ | Periodic local index monitor interval in seconds (default: 300) |
MCP_BACKGROUND_INDEX_INITIAL_DELAY_SECONDS | โ | Initial delay before the first periodic local index check in seconds (default: 30) |
MCP_SEARCH_TURN_STATUS_MODE | โ | Turn-status user message policy: always (default), final-only, or off |
SEARCH_BASH_TOOLS | โ | Enable bash during search runs: 1 (on, default), 0 (off) |
SEARCH_LSP_TOOLS | โ | Enable LSP-assisted search: 1 (on), 0 (off, default) |
MCP_BASE_DIR | โ | Project root override (auto-detected via MCP Roots โ Git โ workspace storage โ CWD) |
MCP_LOGGING | โ | File logging: off (default), safe, full |
MCP_DOTENV_PATH | โ | Path to .env file for centralized config |
* Optional if both: (1) APPLY_PROVIDER and SEARCH_PROVIDER are non-Relace providers, and (2) MCP_RETRIEVAL_BACKEND is codanna, chunkhound, or none.
For .env usage, encoding settings, custom LLM providers, and more, see docs/advanced.md.
Tools
Always available: fast_apply, agentic_search. agentic_retrieval requires MCP_SEARCH_RETRIEVAL=1. Cloud tools are available only when MCP_RETRIEVAL_BACKEND=relace. index_status is available for relace, codanna, and chunkhound, and hidden when MCP_RETRIEVAL_BACKEND=none.
Use MCP-native discovery surfaces: list_tools() for tools and list_resources() for resources.
For detailed parameters, see docs/tools.md.
Language Support
LSP tools use external language servers installed on your system.
| Language | Language Server | Install Command |
|---|---|---|
| Python | basedpyright | (bundled) |
| TypeScript/JS | typescript-language-server | npm i -g typescript-language-server typescript |
| Go | gopls | go install golang.org/x/tools/gopls@latest |
| Rust | rust-analyzer | rustup component add rust-analyzer |
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.
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra benchmark
# Build dataset from Hugging Face
uv run --extra benchmark python -m benchmark.cli.build_locbench --output artifacts/data/raw/locbench_v1.jsonl
# Run evaluation
uv run --extra benchmark python -m benchmark.cli.run --dataset artifacts/data/raw/locbench_v1.jsonl --limit 20
All benchmark artifacts are written under benchmark/.data/.
For grid search, analysis tools, and metrics interpretation, see docs/benchmark.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 or message | Solution |
|---|---|
RELACE_API_KEY is required ... | Set RELACE_API_KEY when using Relace providers or cloud tools |
NEEDS_MORE_CONTEXT | Include 1-3 unique anchor lines near the target block |
INVALID_PATH | Verify the path exists and is inside MCP_BASE_DIR or an allowed extra path |
FILE_TOO_LARGE | File exceeds 10MB; split the change into smaller files or edits |
ENCODING_ERROR | Set RELACE_DEFAULT_ENCODING explicitly for non-UTF-8 projects |
AUTH_ERROR | Verify the API key and provider configuration |
RATE_LIMIT | Retry later or reduce request volume |
NETWORK_ERROR / TIMEOUT_ERROR | Check network access and retry |
APPLY_NOOP | Add more specific anchors or concrete new lines so the merge can produce a diff |
MARKER_LEAKAGE | Ensure placeholder markers are used only as placeholders, not expected literal output |
TRUNCATION_DETECTED | Split large deletion-heavy edits or use explicit remove directives |
BLAST_RADIUS_EXCEEDED | Break the change into smaller, more local edits |
Development
git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra dev --extra benchmark
uv run pytest
uv run --extra dev --extra benchmark pytest benchmark/tests -q
License
MIT
