Relace Mcp

English | 简体中文

Unofficial Relace MCP Server

[](https://pypi.org/project/relace-mcp/) [](https://www.python.org/downloads/) [](LICENSE)

[](https://scorecard.dev/viewer/?uri=github.com/possible055/relace-mcp)

> 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 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](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](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](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](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: possible055
• Source: possible055/relace-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.