rust-analyzer-mcp

rust-analyzer-mcp is a local stdio MCP server that gives coding agents Rust IDE intelligence through rust-analyzer.

It exposes readonly ra_* MCP tools for hover, definitions, implementations, references, document symbols, workspace symbols, completions, inlay hints, macro expansion previews, call hierarchy, formatting edits, code actions, rename previews, diagnostics, workspace diagnostics, and workspace switching. Formatting, code action, macro expansion, and rename tools return previews only; they do not mutate files.

It also exposes fixed cargo_* tools for common Rust verification, builds, and workspace inspection: cargo_build, cargo_check, cargo_test, cargo_clippy, cargo_fmt_check, and cargo_metadata. Cargo tools are enabled by default and can be disabled with --disable-cargo-tools.

Prerequisites

• Rust toolchain
• rust-analyzer installed and available on PATH

rustup component add rust-analyzer

• A Rust project or workspace with Cargo.toml

Build

cargo build --release

Run

./target/release/rust-analyzer-mcp --workspace /path/to/project

Disable cargo tools when you want rust-analyzer-only behavior:

./target/release/rust-analyzer-mcp --workspace /path/to/project --disable-cargo-tools

If --workspace is omitted, the server uses the current working directory.

The server uses stdio for MCP protocol messages. It never writes logs, banners, or human text to stdout. Logs and CLI help/errors go to stderr.

First 5 Minutes

1. Build the binary:

cargo build --release

2. Confirm local dependencies:

rust-analyzer --version
cargo --version

3. Add the binary to your MCP client config with --workspace /absolute/path/to/project.

4. Call server_info from the client. It reports the active workspace, server version, stdio transport, cargo tool state, rust-analyzer path/version, cargo path/version, limits, and advertised tool groups.

Claude Code

Create .mcp.json in your project:

{
  "mcpServers": {
    "rust-analyzer": {
      "command": "/absolute/path/to/rust-analyzer-mcp",
      "args": ["--workspace", "/absolute/path/to/project"]
    }
  }
}

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "rust-analyzer": {
      "command": "/absolute/path/to/rust-analyzer-mcp",
      "args": ["--workspace", "/absolute/path/to/project"]
    }
  }
}

Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.rust-analyzer]
command = "/absolute/path/to/rust-analyzer-mcp"
args = ["--workspace", "/absolute/path/to/project"]

Generic MCP Clients

Configure the client to launch the binary over stdio:

{
  "command": "/absolute/path/to/rust-analyzer-mcp",
  "args": ["--workspace", "/absolute/path/to/project"],
  "transport": "stdio"
}

Tools

All tools return pretty JSON as MCP text content:

{
  "ok": true,
  "tool": "ra_definition",
  "workspace_root": "/path/to/project",
  "input": {},
  "result": {},
  "notes": [],
  "truncated": false
}

Recoverable errors return ok: false with an error and hint.

server_info

Report local runtime and readiness information.

Params:

{}

The response includes server name/version, stdio transport, active workspace root, workspace warnings, whether cargo tools are enabled, rust-analyzer path/version, cargo path/version, output and timeout limits, and tool groups.

ra_set_workspace

Change the active workspace root and restart rust-analyzer.

Params:

{ "workspace_path": "/path/to/project" }

ra_hover

Get hover/type/documentation information at a position.

Params:

{ "file_path": "src/lib.rs", "line": 0, "character": 7 }

ra_definition

Find definitions at a position.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "context_lines": 8,
  "include_snippets": true
}

ra_implementations

Find implementations for a trait, type, or symbol at a position.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "max_results": 50,
  "context_lines": 8,
  "include_snippets": true
}

ra_references

Find references at a position.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "include_declaration": true,
  "max_results": 50,
  "context_lines": 4,
  "include_snippets": true
}

ra_document_symbols

List symbols in a file.

Params:

{ "file_path": "src/lib.rs" }

ra_workspace_symbols

Search workspace-wide symbols by query.

Params:

{ "query": "Parser", "max_results": 50 }

ra_completion

Get completion suggestions at a position.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "max_results": 50
}

ra_inlay_hints

Return rust-analyzer inlay hints grouped by source line. By default the tool requests the whole file. Supply both start_line and end_line for an inclusive selected line range. kinds accepts type, parameter, and other; omit it to return all hints from rust-analyzer. Line and character positions are zero-based LSP positions; character is a UTF-16 code unit offset. The response uses the top-level MCP envelope truncated flag when max_hints limits output. Raw hints are informational only; this tool does not execute commands, apply text edits, or mutate files.

Params:

{
  "file_path": "src/lib.rs",
  "start_line": 0,
  "end_line": 80,
  "kinds": ["type", "parameter"],
  "max_hints": 200,
  "include_raw": false
}

The response includes total, returned, groups, and optional raw_hints. The top-level truncated flag is true when max_hints limits output.

ra_macro_expansion

Preview rust-analyzer macro expansion at a position. The tool does not mutate files.

Params:

{ "file_path": "src/lib.rs", "line": 0, "character": 7 }

ra_call_hierarchy

Return prepared call hierarchy items with bounded incoming and outgoing calls.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "max_items": 20,
  "max_calls_per_item": 50
}

ra_format

Return formatting text edits for a file without applying them.

Params:

{ "file_path": "src/lib.rs" }

ra_code_actions

Return available code actions for a selected range without applying edits.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 0,
  "end_line": 0,
  "end_character": 10
}

ra_rename_preview

Return the workspace edits rust-analyzer would make for a symbol rename without applying them.

Params:

{
  "file_path": "src/lib.rs",
  "line": 0,
  "character": 7,
  "new_name": "new_symbol_name"
}

The response includes the raw LSP workspace_edit plus document_count, change_count, and resource_operation_count summary fields.

ra_diagnostics

Open a file, wait briefly, and return cached diagnostics for that file.

Params:

{ "file_path": "src/lib.rs", "wait_ms": 1500 }

ra_workspace_diagnostics

Return known cached diagnostics across the active workspace.

Params:

{ "wait_ms": 3000, "max_files": 100, "max_diagnostics": 300 }

cargo_build

Run fixed cargo build in the active workspace.

Cargo tool parameters are structured, validated, and enforced by the server; requests that violate these rules are rejected instead of forwarded to cargo. workspace cannot be combined with package; all_features cannot be combined with features or no_default_features; string values such as package, features, and target must not be empty or start with -; feature values also must not contain ,.

Params:

{
  "workspace": false,
  "package": "optional package name",
  "features": ["optional", "features"],
  "all_features": false,
  "no_default_features": false,
  "target": "optional target triple",
  "all_targets": false,
  "release": false,
  "locked": false,
  "offline": false,
  "frozen": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 60000,
  "max_stderr_bytes": 60000
}

cargo_check

Run fixed cargo check in the active workspace.

Cargo tool parameters are structured, validated, and enforced by the server; requests that violate these rules are rejected instead of forwarded to cargo. workspace cannot be combined with package; all_features cannot be combined with features or no_default_features; string values such as package, features, and target must not be empty or start with -; feature values also must not contain ,.

Params:

{
  "workspace": false,
  "package": "optional package name",
  "features": ["optional", "features"],
  "all_features": false,
  "no_default_features": false,
  "target": "optional target triple",
  "all_targets": false,
  "release": false,
  "locked": false,
  "offline": false,
  "frozen": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 60000,
  "max_stderr_bytes": 60000
}

cargo_test

Run fixed cargo test in the active workspace.

Params:

{
  "workspace": false,
  "package": "optional package name",
  "features": ["optional", "features"],
  "all_features": false,
  "no_default_features": false,
  "target": "optional target triple",
  "all_targets": false,
  "locked": false,
  "offline": false,
  "frozen": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 60000,
  "max_stderr_bytes": 60000,
  "test_filter": "optional test name or substring",
  "nocapture": false
}

cargo_clippy

Run fixed cargo clippy in the active workspace. This tool does not append -- -D warnings.

Params:

{
  "workspace": false,
  "package": "optional package name",
  "features": ["optional", "features"],
  "all_features": false,
  "no_default_features": false,
  "target": "optional target triple",
  "all_targets": false,
  "release": false,
  "locked": false,
  "offline": false,
  "frozen": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 60000,
  "max_stderr_bytes": 60000
}

cargo_fmt_check

Run fixed cargo fmt --check in the active workspace.

Params:

{
  "package": "optional package name",
  "all": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 60000,
  "max_stderr_bytes": 60000
}

cargo_metadata

Run fixed cargo metadata --format-version 1 in the active workspace.

Params:

{
  "features": ["optional", "features"],
  "all_features": false,
  "no_default_features": false,
  "filter_platform": "optional target triple",
  "no_deps": false,
  "locked": false,
  "offline": false,
  "frozen": false,
  "timeout_ms": 120000,
  "max_stdout_bytes": 120000,
  "max_stderr_bytes": 60000
}

When metadata JSON parses successfully, the response includes metadata_json and omits the duplicated raw stdout payload to keep the MCP response bounded.

Safety Model

• User-supplied paths are resolved inside the configured workspace root.
• Absolute paths are accepted only when they canonicalize inside the workspace.
• Symlink escapes and .. escapes are rejected.
• External crate locations returned by rust-analyzer are marked as external dependency source.
• External snippets are readonly, bounded, and only read when the URI came from rust-analyzer.
• server_info is readonly and reports local runtime readiness.
• ra_* tools are readonly analysis and preview tools.
• ra_format, ra_code_actions, ra_macro_expansion, and ra_rename_preview return previews only. They never write edits to disk.
• ra_set_workspace mutates server state by switching the active workspace and restarting rust-analyzer. It does not write workspace files.
• cargo_* tools execute fixed cargo commands in the active workspace. They do not expose arbitrary shell commands or free-form cargo subcommands.
• Cargo commands may execute workspace code, build scripts, proc macros, and tests. Those executions can have arbitrary project-defined side effects, write artifacts under target/, and update Cargo.lock unless locked or frozen is used.
• Cargo tools are enabled by default and can be disabled with --disable-cargo-tools.
• No write/apply file-editing tools are exposed in the MVP.

Troubleshooting

rust-analyzer not found

Install it and make sure it is on PATH:

rustup component add rust-analyzer
rust-analyzer --version

Invalid workspace

Use a directory that exists. The server warns when the workspace root does not contain Cargo.toml.

No diagnostics yet

rust-analyzer may still be indexing. Retry ra_diagnostics or increase wait_ms.

No rename edits returned

Make sure the cursor is on the symbol name and that rust-analyzer has finished indexing the workspace.

cargo not found

Install Rust and make sure cargo is on PATH:

rustup --version
cargo --version

cargo tool timed out

Increase timeout_ms for large workspaces or run a narrower package/test selection. Timeout cleanup is best effort; the server kills the spawned cargo process and stops output collection after timeout, but it does not claim full process-tree cleanup.

cargo tools disabled

Restart the server without --disable-cargo-tools if you want to use cargo_build, cargo_check, cargo_test, cargo_clippy, cargo_fmt_check, or cargo_metadata.

stdout logging breaks stdio MCP

Do not add println!, banners, or stdout logging to this server. stdout is reserved for MCP protocol messages only.

External crate definitions

Definitions and references can point into Cargo registry or rustup source paths. These are returned as external dependency source locations, with bounded snippets when safe.

Current Scope

The public MVP is local stdio only. It intentionally does not include an HTTP transport, hosted mode, authentication, multi-user state, or write/apply file-editing tools.

Future expansion should stay within the same safety model unless the server explicitly grows a separate remote transport design.

Development

cargo fmt
cargo fmt --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all