bazel-mcp

Integrate Bazel with AI coding assistants via the Model Context Protocol

bazel-mcp is a Model Context Protocol server that exposes your Bazel workspace to AI assistants like Claude (in VS Code or Cursor). It enables AI assistants to understand and work with Bazel projects by providing direct access to build, test, run, and query capabilities.

Why bazel-mcp?

• 🤖 AI-Native Development: Let AI assistants build, test, and run Bazel targets directly
• 📦 Zero Configuration: Automatically discovers all Bazel targets in your workspace
• 🔄 Real-time Streaming: See build and test output as it happens
• 🎯 Smart Context: AI understands your build graph and dependencies
• ⚡ Fast Iteration: No context switching between AI chat and terminal

Installation

From PyPI (Recommended)

pip install bazel-mcp

From Source

git clone https://github.com/sandeepnmenon/py_bazel_mcp
cd py_bazel_mcp
pip install -e .

Quick Start

1. Configure Your Editor

VS Code (Claude Extension)

Create .vscode/mcp.json in your workspace:

{
  "mcpServers": {
    "bazel-mcp": {
      "command": "bazel-mcp",
      "args": ["--repo", "${workspaceFolder}"]
    }
  }
}

Cursor

Add as a custom MCP server:

1. Settings → MCP Servers → Add Custom Server
2. Command: bazel-mcp
3. Args: --repo /path/to/your/bazel/workspace

2. Verify Setup

Ask your AI assistant:

"Can you list all Bazel targets in this workspace?"

The assistant should use the bazel_list_targets tool and show your project's targets.

Features

🛠️ Available Tools

Tool	Description
bazel_list_targets	List all discovered targets grouped by type
bazel_query	Run arbitrary Bazel query expressions
bazel_build	Build one or more targets with streaming output
bazel_run	Run a binary target with arguments
bazel_test	Run tests with optional filters
repo_setup	Run project setup scripts

📚 Resources

• bazel://targets: Returns a JSON snapshot of all discovered targets in your workspace

Usage Examples

Building and Testing

"Build the server binary"

# AI will use:
bazel_build(targets=["//apps:server"])

"Run all tests matching 'Vector' in the math library"

# AI will use:
bazel_test(
    targets=["//lib/math:all"],
    flags=["--test_filter=Vector.*"]
)

Dependency Analysis

"What depends on the database library?"

# AI will use:
bazel_query(expr="rdeps(//..., //lib:database)")

"Show me the build graph for the main app"

# AI will use:
bazel_query(expr="deps(//main:app)")

Running Binaries

"Run the CLI tool with port 8080"

# AI will use:
bazel_run(
    target="//tools:cli",
    args=["--port=8080"]
)

API Documentation

Tool Reference

bazel_list_targets - List all discovered targets

Parameters:

• refresh (bool, optional): Force re-discovery of targets

Returns: JSON with targets grouped by kind (cc_library, cc_binary, py_library, py_binary, cc_test, py_test)

bazel_query - Run Bazel query expressions

Parameters:

• expr (str, required): Bazel query expression
• flags (list, optional): Additional Bazel flags

Example:

bazel_query(expr="deps(//main:app)")
bazel_query(expr="kind('cc_test', //...)", flags=["--output=label_kind"])

bazel_build - Build targets

Parameters:

• targets (list, required): Target labels to build
• flags (list, optional): Bazel build flags

Example:

bazel_build(targets=["//src:lib", "//apps:server"])
bazel_build(targets=["//..."], flags=["--config=debug"])

bazel_run - Run a binary target

Parameters:

• target (str, required): Binary target label
• args (list, optional): Arguments for the binary
• flags (list, optional): Bazel run flags

Example:

bazel_run(target="//tools:cli", args=["--port=8080"])

bazel_test - Run tests

Parameters:

• targets (list, optional): Test targets (default: //...)
• flags (list, optional): Test flags

Example:

bazel_test(targets=["//tests:unit_tests"])
bazel_test(targets=["//..."], flags=["--test_filter=MyTest.*"])

repo_setup - Run setup scripts

Parameters:

• skipInstall (bool, optional): Skip install scripts

Runs (if present):

• ./tools/setup_cache.sh
• ./install/install_all.sh

Advanced Configuration

Environment Variables

Variable	Description	Default
BAZEL_PATH	Path to Bazel executable	bazel
BAZELISK	Use Bazelisk if available	auto-detect
PYTHONPATH	Python module search path	Required for source installs

Using Bazelisk (Recommended)

Bazelisk automatically manages Bazel versions:

# Install Bazelisk
wget -O bazelisk https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64
chmod +x bazelisk
sudo mv bazelisk /usr/local/bin/bazel

# bazel-mcp will automatically detect and use it

Troubleshooting

Issue	Solution
"No module named 'mcp'"	Install with pip install bazel-mcp
"Not a valid Bazel repository"	The server must be run from a directory containing WORKSPACE, WORKSPACE.bazel, or MODULE.bazel. Check your --repo path.
"bazel query failed"	Ensure you're in a Bazel workspace (has WORKSPACE or MODULE.bazel)
Editor not detecting server	Restart editor after configuration
Logs not streaming	Add --verbose_failures flag to see detailed output

Development

Setting up for Development

git clone https://github.com/sandeepnmenon/py_bazel_mcp
cd py_bazel_mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

Running Tests

pytest tests/

Project Structure

py_bazel_mcp/
├── src/bazel_mcp/
│   ├── __init__.py
│   ├── server.py      # MCP server implementation
│   ├── bazel.py       # Bazel command wrappers
│   ├── targets.py     # Target discovery & caching
│   └── util.py        # Utility functions
├── tests/             # Unit tests
├── pyproject.toml     # Package configuration
└── README.md          # Documentation

Contributing

Contributions are welcome!

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Reporting Issues

Please report issues on our GitHub Issues page. Include:

• Your environment (OS, Python version, Bazel version)
• Steps to reproduce
• Expected vs actual behavior

License

MIT License - see LICENSE file for details.

Acknowledgments

• Model Context Protocol - The protocol that makes this possible
• Bazel - The build system we're integrating with
• The MCP community for inspiration and examples

Links

• Documentation: GitHub Wiki
• PyPI Package: bazel-mcp
• Issue Tracker: GitHub Issues

---

Built for developers using Bazel and AI assistants