The Relace MCP Server provides AI-powered code editing and intelligent codebase search through Relace's API, integrating with MCP-compatible editors like Cursor, Claude Code, Windsurf, VS Code, and Codex CLI.
Core Capabilities:
Fast Code Editing (
fast_apply) - Apply code changes at 10,000+ tokens/sec to existing or new files with intelligent context-aware merging and smart truncation placeholdersAgentic Local Search (
fast_search) - Explore codebases using natural language queries with an autonomous agent that uses grep, ls, and file viewing tools
Cloud Capabilities (requires RELACE_CLOUD_TOOLS=1):
Cloud Synchronization (
cloud_sync) - Upload local codebases to Relace Cloud for semantic indexing with incremental, safe full, and mirror full sync modesSemantic Search (
cloud_search) - Perform AI-powered semantic code search using embeddings and reranking to find conceptually related code without exact keyword matchesRepository Management - List repositories (
cloud_list), check sync status (cloud_info), and delete repositories with local state cleanup (cloud_clear)
Key Features:
Automatic project root detection via MCP Roots or Git
Cross-platform support (Linux, macOS, Windows via WSL for full features)
Respects
.gitignoreduring cloud syncConfigurable via environment variables or
.envfilesOptional file logging to platform-specific directories
Custom encoding support for legacy repositories
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Relace MCP Serversearch for authentication middleware in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 for Relace — AI-powered instant code merging and agentic codebase search.
Prerequisites
uv — Python package manager
git — for
cloud_syncto respect.gitignoreripgrep (
rg) — recommended forfast_search(falls back to Python regex if unavailable)
Platform Notes
Platform | Status | Notes |
Linux | ✅ Fully supported | Primary development platform |
macOS | ✅ Fully supported | All features available |
Windows | ⚠️ Partial |
|
Windows users: The
bashtool requires a Unix shell. Install WSL for full feature parity, or use other exploration tools (view_file,grep_search,glob).
Quick Start
Get your API key from Relace Dashboard, then add to your MCP client:
~/.cursor/mcp.json
~/.codeium/windsurf/mcp_config.json
.vscode/mcp.json
~/.codex/config.toml
Note:
RELACE_BASE_DIRis optional. If not set, the server auto-detects via MCP Roots or Git. If set, it must be an absolute path.
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
Environment Variables
Variable | Required | Description |
| ✅ | API key from Relace Dashboard |
| ❌ | Absolute path to project root (auto-detected via MCP Roots if not set) |
| ❌ | Path to |
| ❌ | Set to |
| ❌ | Set to |
| ❌ | Force file encoding (e.g., |
Using a .env File
Instead of setting many environment variables in your MCP config, you can use a centralized .env file:
1. Create a (e.g., ~/.config/relace/.env):
2. Point to it in your MCP config:
Note: Variables set directly in
envtake precedence over those in the.envfile.
Note: When
RELACE_BASE_DIRis not set, the server automatically detects your project root using:
MCP Roots (workspace info from your editor)
Git repository root (if found)
Current working directory (fallback)
⚠️ Warning: Fallback to CWD/Git can be unstable if MCP Roots fail. Explicit
RELACE_BASE_DIRis recommended.
For advanced settings, see docs/advanced.md.
Tools
Core Tools (always available)
Tool | Description |
| Apply code edits at 10,000+ tokens/sec |
| Agentic codebase search with natural language |
Cloud Tools (requires RELACE_CLOUD_TOOLS=1)
Tool | Description |
| Upload local codebase to Relace Cloud |
| Semantic search over cloud-synced repos |
| List cloud repositories |
| Get sync status |
| Delete cloud repo and local state |
For detailed parameters and examples, see docs/tools.md.
Logging
Note: File logging is opt-in. Enable with
RELACE_LOGGING=1.
Operation logs are written to a cross-platform state directory:
Linux:
~/.local/state/relace/relace.logmacOS:
~/Library/Application Support/relace/relace.logWindows:
%LOCALAPPDATA%\relace\relace.log
For log format and advanced options, see docs/advanced.md.
Troubleshooting
Common issues:
RELACE_API_KEY is not set: Set the key in your environment or MCP config.RELACE_BASE_DIR does not exist/INVALID_PATH: Ensure the path exists and is withinRELACE_BASE_DIR.NEEDS_MORE_CONTEXT/APPLY_NOOP: Include 1–3 real anchor lines before and after the target block.FILE_TOO_LARGE: File exceeds the 1MB size limit; split large files or increase limit.ENCODING_ERROR: Cannot detect file encoding; setRELACE_DEFAULT_ENCODINGexplicitly.FILE_NOT_WRITABLE/PERMISSION_ERROR: Check file and directory write permissions.AUTH_ERROR: Verify yourRELACE_API_KEYis valid and not expired.RATE_LIMIT: Too many requests; wait and retry later.TIMEOUT_ERROR/NETWORK_ERROR: Check network connectivity; increase timeout viaRELACE_TIMEOUT_SECONDS.
Windows users: The
bashtool infast_searchis unavailable on Windows. Use WSL or rely on other exploration tools.