What can you do with this server?

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 placeholders * Agentic 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 modes * Semantic Search (cloud_search) - Perform AI-powered semantic code search using embeddings and reranking to find conceptually related code without exact keyword matches * Repository 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 .gitignore during cloud sync * Configurable via environment variables or .env files * Optional file logging to platform-specific directories * Custom encoding support for legacy repositories

How do I use Relace MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Relace MCP Server search 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

PyPI Python 3.11+ License: MIT 100% AI-Generated OpenSSF Scorecard

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 with MCP_RETRIEVAL_BACKEND)
Cloud Search — Semantic code search over cloud-synced repositories

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:

~/.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 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

~/.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"
      }
    }
  }
}

.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/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
`RELACE_CLOUD_TOOLS`	❌	Set to `1` to enable cloud tools
`MCP_SEARCH_RETRIEVAL`	❌	Set to `1` to register the `agentic_retrieval` tool
`MCP_RETRIEVAL_BACKEND`	❌	Semantic retrieval backend: `relace` (default), `codanna`, `chunkhound`, `auto`, 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 the internal `bash` subtool used inside `agentic_search` / `agentic_retrieval`: `1` (on), `0` (off, default)
`SEARCH_LSP_TOOLS`	❌	Enable the internal `find_symbol` / `search_symbol` subtools used inside `agentic_search` / `agentic_retrieval`: `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) RELACE_CLOUD_TOOLS=false.

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

Tools

Top-level tools always available: fast_apply, agentic_search. index_status is exposed only when RELACE_CLOUD_TOOLS=1 or a local index CLI (codanna / chunkhound) is available in PATH. Cloud tools require RELACE_CLOUD_TOOLS=1. agentic_retrieval requires MCP_SEARCH_RETRIEVAL=1, and its semantic backend is selected via MCP_RETRIEVAL_BACKEND.

Use MCP-native discovery surfaces: list_tools() for tools and list_resources() for resources.

index_status now also reports a background_monitor summary for the opt-in local index monitor. The monitor is intentionally limited to single-process deployments with a pinned MCP_BASE_DIR; for multi-worker or multi-pod HTTP deployments, prefer backend-native watch/daemon flows or an external scheduler.

SEARCH_BASH_TOOLS and SEARCH_LSP_TOOLS do not add new top-level entries to list_tools(). They only expand the internal toolset used while agentic_search / agentic_retrieval explore the codebase.

agentic_retrieval can use stale semantic hints and then verify them against live code. It does not run cloud_sync implicitly; use cloud_sync as the explicit maintenance tool when you want to refresh the cloud index ahead of retrieval.

Live local exploration keeps .gitignore filtering in place, and exact-text probes automatically use a faster literal search path when regex features are unnecessary.

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

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Relace MCP Server

Unofficial Relace MCP Server

Features

Quick Start

Configuration

Tools

Language Support

Dashboard

Benchmark

Platform Support

Troubleshooting

Development

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API