rust-clippy-mcp-server

A Model Context Protocol (MCP) server for Rust Clippy — the Rust linter. Enables AI assistants to run clippy checks, auto-fix warnings, explain lint rules, configure lint levels, and detect the Rust toolchain environment.

Features

• 🔍 clippy_check — Run cargo clippy and get structured JSON diagnostic results
• 💾 clippy_check_save — Run cargo clippy and save results to local files (JSON + Markdown + Raw), with smart inline/summary JSON output
• 🔧 clippy_fix — Auto-fix clippy warnings with cargo clippy --fix
• 📖 clippy_explain — Get detailed explanations of any clippy lint rule
• ⚙️ clippy_configure — Configure lint levels (allow/warn/deny/forbid) in Cargo.toml or as file attributes
• 🔎 clippy_detect — Detect Rust toolchain environment (cargo, rustc, rustup, clippy) with install instructions
• 📄 clippy config resource — Read project clippy configuration files
• 🛠️ troubleshooting resource — Diagnose environment issues and get fix instructions

Quick Start

Usage with npx

npx rust-clippy-mcp-server

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "rust-clippy": {
      "command": "npx",
      "args": ["-y", "rust-clippy-mcp-server"]
    }
  }
}

Cursor / Roo / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "rust-clippy": {
      "command": "npx",
      "args": ["-y", "rust-clippy-mcp-server"]
    }
  }
}

Tip: If the server cannot find your Rust toolchain, add env to the config — see Troubleshooting.

Prerequisites

• Node.js >= 18.0.0
• Rust toolchain (cargo, rustc) — Install Rust
• Clippy — Usually included with Rust. If not: rustup component add clippy

Tools

clippy_detect

Detect the Rust toolchain environment. Checks if cargo, rustc, rustup, and clippy are installed, reports their versions, and provides installation instructions if any tool is missing.

Parameters: None

clippy_check

Run cargo clippy on a Rust project and return structured JSON diagnostic results. Respects the project's own clippy configuration by default. Supports real-time progress reporting and cancellation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | target | string | | Build target (e.g. --lib, --bin name) | | features | string[] | | Features to enable | | all_features | boolean | | Enable all features | | no_default_features | boolean | | Disable default features | | extra_args | string[] | | Extra arguments passed to clippy after --, e.g. ["-W", "clippy::all"] | | timeout | number | | Maximum timeout in seconds (default: 1800) |

Returns a JSON object:

{
  "success": true,
  "summary": { "total": 5, "errors": 1, "warnings": 4 },
  "diagnostics": [
    {
      "level": "warning",
      "code": "clippy::needless_return",
      "message": "unneeded `return` statement",
      "file": "src/main.rs",
      "line": 42,
      "column": 5,
      "rendered": "warning: unneeded `return` statement\n --> src/main.rs:42:5\n ...",
      "suggestion": { "replacement": "a + b", "applicability": "MachineApplicable" },
      "help": ["remove `return`"]
    }
  ]
}

On error: { "success": false, "error": "..." }

clippy_check_save

Run cargo clippy and save the results to local files (JSON + Markdown + Raw). If the JSON result is small (≤ max_inline_size), the full diagnostics are returned inline; otherwise only a summary with top issues and file paths are returned so the LLM can read the files later.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | output_dir | string | ✅ | Directory to save the report files (created if needed) | | target | string | | Build target (e.g. --lib, --bin name) | | features | string[] | | Features to enable | | all_features | boolean | | Enable all features | | no_default_features | boolean | | Disable default features | | extra_args | string[] | | Extra arguments passed to clippy after --, e.g. ["-W", "clippy::all"] | | timeout | number | | Maximum timeout in seconds (default: 1800) | | max_inline_size | number | | Max JSON size in bytes to return inline (default: 32768 = 32KB) |

Returns a JSON object. When data is small enough:

{
  "success": true,
  "summary": { "total": 5, "errors": 1, "warnings": 4 },
  "files": {
    "json": "/path/to/clippy-report.json",
    "markdown": "/path/to/clippy-report.md",
    "raw": "/path/to/clippy-report.raw.txt"
  },
  "diagnostics": [ ... ]
}

When data exceeds max_inline_size:

{
  "success": true,
  "summary": { "total": 150, "errors": 3, "warnings": 147 },
  "files": { "json": "...", "markdown": "...", "raw": "..." },
  "truncated": true,
  "truncation_reason": "Full JSON is 128.0KB, exceeds inline limit of 32.0KB. Read the JSON file for complete diagnostics: ...",
  "top_issues_by_code": [
    { "code": "clippy::needless_return", "count": 45 }
  ],
  "top_issues_by_file": [
    { "file": "src/main.rs", "count": 50 }
  ]
}

clippy_fix

Auto-fix clippy warnings using cargo clippy --fix. Respects the project's own clippy configuration by default. Supports real-time progress reporting and cancellation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | allow_dirty | boolean | | Allow fixing in dirty working directory | | allow_staged | boolean | | Allow fixing with staged changes | | allow_no_vcs | boolean | | Allow fixing even if no VCS (git) is detected | | target | string | | Build target | | features | string[] | | Features to enable | | extra_args | string[] | | Extra arguments passed to clippy after --, e.g. ["-W", "clippy::all"] | | timeout | number | | Maximum timeout in seconds (default: 1800) |

clippy_explain

Explain a specific clippy lint rule with examples.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | lint_name | string | ✅ | Lint name (e.g. needless_return or clippy::needless_return) |

clippy_configure

Configure clippy lint levels for a project.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | project_path | string | ✅ | Path to the Rust project directory | | action | enum | ✅ | allow, warn, deny, or forbid | | lints | string[] | ✅ | List of lint names to configure | | scope | enum | | project (Cargo.toml) or file (attributes) |

Resources

clippy://config/{project_path}

Read the clippy configuration for a Rust project, including:

• clippy.toml / .clippy.toml contents
• Cargo.toml [lints.clippy] section

clippy://troubleshooting

Diagnose environment issues (missing CARGO_HOME, RUSTUP_HOME, PATH problems) and get step-by-step fix instructions for different MCP clients.

Troubleshooting

If the MCP server cannot find your Rust toolchain (e.g. cargo not found), the most common cause is that the MCP client process does not inherit your shell environment variables.

Fix: Add environment variables to your MCP client config

{
  "mcpServers": {
    "rust-clippy": {
      "command": "npx",
      "args": ["-y", "rust-clippy-mcp-server"],
      "env": {
        "CARGO_HOME": "/path/to/your/.cargo",
        "RUSTUP_HOME": "/path/to/your/.rustup"
      }
    }
  }
}

Windows example:

"env": {
  "CARGO_HOME": "C:\\Users\\YourName\\.cargo",
  "RUSTUP_HOME": "C:\\Users\\YourName\\.rustup"
}

macOS/Linux example (default paths):

"env": {
  "CARGO_HOME": "/home/username/.cargo",
  "RUSTUP_HOME": "/home/username/.rustup"
}

You can also use the clippy_detect tool or read the clippy://troubleshooting resource for detailed diagnostics.

Project Structure

rust-clippy-mcp-server/
├── src/
│   ├── index.ts                # Entry point, MCP Server setup & tool/resource registration
│   ├── tools/
│   │   ├── clippy-check.ts     # clippy_check tool
│   │   ├── clippy-check-save.ts# clippy_check_save tool
│   │   ├── clippy-fix.ts       # clippy_fix tool
│   │   ├── clippy-explain.ts   # clippy_explain tool
│   │   ├── clippy-configure.ts # clippy_configure tool
│   │   └── clippy-detect.ts    # clippy_detect tool
│   ├── resources/
│   │   ├── clippy-config.ts    # clippy config resource
│   │   └── troubleshooting.ts  # troubleshooting resource
│   └── utils/
│       ├── cargo-runner.ts     # Cargo/command execution with enhanced PATH
│       ├── cargo-progress.ts   # Cargo build progress tracking
│       ├── diagnostics.ts      # Clippy JSON output parsing
│       ├── detect.ts           # Toolchain environment detection
│       ├── progress.ts         # MCP progress reporting utilities
│       ├── report-writer.ts    # Report file writer (JSON/Markdown/raw)
│       └── validate.ts         # Project path validation
├── package.json
├── tsconfig.json
└── README.md

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run directly
npm start

# Run tests
npm test

# Inspect with MCP Inspector
npm run inspect

License

MIT