# Cargo MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides tools for running Cargo commands. This server allows AI agents to interact with Rust projects through Cargo, enabling automated builds, tests, documentation generation, and more.
## Features
The server provides the following Cargo tools:
- **`cargo_build`** - Build a Rust project with Cargo
- **`cargo_test`** - Run tests for a Rust project
- **`cargo_run`** - Run a Rust binary
- **`cargo_check`** - Check a project for errors without building
- **`cargo_clippy`** - Run Clippy linter
- **`cargo_fmt`** - Format Rust code using rustfmt
- **`cargo_doc`** - Generate documentation
- **`cargo_clean`** - Clean build artifacts
- **`cargo_tree`** - Display dependency tree
- **`cargo_update`** - Update dependencies in Cargo.lock
- **`cargo_bench`** - Run benchmarks
## Installation
### Prerequisites
- Python 3.8 or higher
- Rust and Cargo installed on your system
- Access to install Python packages
### Install from source
1. Clone this repository:
```bash
git clone <repository-url>
cd cargo-mcp
```
2. Install the package:
```bash
pip install -e .
```
## Usage
### With Claude Desktop
Add the server to your `claude_desktop_config.json`:
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"cargo-mcp": {
"command": "cargo-mcp"
}
}
}
```
### With other MCP clients
The server can be used with any MCP-compatible client. Start the server using:
```bash
cargo-mcp
```
### Testing with MCP Inspector
You can test the server using the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector cargo-mcp
```
## Tool Documentation
### cargo_build
Build a Rust project with Cargo.
**Parameters:**
- `release` (boolean, optional): Build in release mode with optimizations
- `features` (array, optional): List of features to activate
- `target` (string, optional): Build for the given target triple
- `workspace_path` (string, optional): Path to the workspace root (auto-detected if not provided)
### cargo_test
Run tests for a Rust project.
**Parameters:**
- `test_name` (string, optional): Name of specific test to run
- `release` (boolean, optional): Run tests in release mode
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
### cargo_run
Run a Rust binary.
**Parameters:**
- `bin_name` (string, optional): Name of the binary to run (for multi-binary projects)
- `args` (array, optional): Arguments to pass to the binary
- `release` (boolean, optional): Run in release mode
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
### cargo_check
Check a Rust project for errors without building it.
**Parameters:**
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
### cargo_clippy
Run Clippy linter on a Rust project.
**Parameters:**
- `fix` (boolean, optional): Automatically apply suggested fixes
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
### cargo_fmt
Format Rust code using rustfmt.
**Parameters:**
- `check` (boolean, optional): Check if files are formatted without modifying them
- `workspace_path` (string, optional): Path to the workspace root
### cargo_doc
Generate documentation for a Rust project.
**Parameters:**
- `open` (boolean, optional): Open documentation in browser after generation
- `no_deps` (boolean, optional): Don't build documentation for dependencies
- `workspace_path` (string, optional): Path to the workspace root
### cargo_clean
Clean build artifacts.
**Parameters:**
- `workspace_path` (string, optional): Path to the workspace root
### cargo_tree
Display dependency tree.
**Parameters:**
- `package` (string, optional): Package to display tree for
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
### cargo_update
Update dependencies in Cargo.lock.
**Parameters:**
- `package` (string, optional): Specific package to update
- `workspace_path` (string, optional): Path to the workspace root
### cargo_bench
Run benchmarks.
**Parameters:**
- `bench_name` (string, optional): Name of specific benchmark to run
- `features` (array, optional): List of features to activate
- `workspace_path` (string, optional): Path to the workspace root
## Project Structure Detection
The server automatically detects Rust projects by searching for `Cargo.toml` files. It walks up the directory tree from the current working directory to find the nearest `Cargo.toml` file and uses that directory as the workspace root.
You can override this behavior by providing the `workspace_path` parameter to any tool.
## Error Handling
The server provides detailed error messages and logs for troubleshooting:
- Checks if Cargo is installed and available in PATH
- Validates that Cargo.toml exists in the target directory
- Captures both stdout and stderr from Cargo commands
- Provides detailed command execution information
## Development
### Setup
1. Clone the repository
2. Install development dependencies:
```bash
pip install -e ".[dev]"
```
### Testing
Run tests using pytest:
```bash
pytest
```
### Code Formatting
Format code using black:
```bash
black src/
```
Lint code using ruff:
```bash
ruff check src/
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For issues and questions:
- Create an issue on GitHub
- Check the [MCP documentation](https://modelcontextprotocol.io) for general MCP questions
