Unofficial Relace MCP Server

Name: Relace MCP Server
Author: possible055

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 for Relace — AI-powered instant code merging and agentic codebase search.

Prerequisites

uv — Python package manager
git — for cloud_sync to respect .gitignore
ripgrep (rg) — recommended for fast_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	`bash` tool unavailable; use WSL for full functionality

Windows users: The bash tool 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

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

claude mcp add relace \ --env RELACE_API_KEY=rlc-your-api-key \ --env RELACE_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", "RELACE_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", "RELACE_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" RELACE_BASE_DIR = "/absolute/path/to/your/project"

Note: RELACE_BASE_DIR is 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
`RELACE_API_KEY`	✅	API key from Relace Dashboard
`RELACE_BASE_DIR`	❌	Absolute path to project root (auto-detected via MCP Roots if not set)
`RELACE_DEFAULT_ENCODING`	❌	Force file encoding (e.g., `gbk` , `big5` ) for legacy repos
`RELACE_ENCODING_SAMPLE_LIMIT`	❌	Max files for auto-detecting encoding (default: `30` )

Note: When RELACE_BASE_DIR is 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_DIR is recommended.

For advanced settings, see docs/advanced.md.

Tools

Tool	Description
`fast_apply`	Apply code edits at 10,000+ tokens/sec
`fast_search`	Agentic codebase search with natural language
`cloud_sync`	Upload local codebase to Relace Cloud
`cloud_search`	Semantic search over cloud-synced repos
`cloud_list`	List cloud repositories
`cloud_info`	Get sync status
`cloud_clear`	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.log
macOS: ~/Library/Application Support/relace/relace.log
Windows: %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 within RELACE_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; set RELACE_DEFAULT_ENCODING explicitly.
FILE_NOT_WRITABLE / PERMISSION_ERROR: Check file and directory write permissions.
AUTH_ERROR: Verify your RELACE_API_KEY is valid and not expired.
RATE_LIMIT: Too many requests; wait and retry later.
TIMEOUT_ERROR / NETWORK_ERROR: Check network connectivity; increase timeout via RELACE_TIMEOUT_SECONDS.