MCP Build Environment Service
Provides secure access to Docker-based containerized build environments for executing builds, running tests, and managing development workflows in isolated containers.
Enables safe Git operations within build environments including status checks, branch management, commits viewing, and repository synchronization with whitelisted commands.
Allows execution of Make build targets within containerized environments for compiling projects, running tests, and managing build artifacts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Build Environment Service checkout the main branch in my-project and run make test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Build Service
A Model Context Protocol (MCP) server that provides access to git repositories for build and test operations. This allows AI assistants to run builds, execute tests, and inspect git repositories on your behalf.
What does it do?
This service provides AI assistants with tools to:
List available git repositories
Execute git commands (status, log, checkout, pull, fetch, diff, show, branch)
Run make targets (build, test, clean, etc.)
List directory contents
Read files from repositories
Query installed build tools and versions
The service runs in a directory containing git repositories and exposes them through the MCP protocol.
Related MCP server: agent-env-mcp
Use case
The typical workflow is:
You develop code in your workspace and push to a git branch
AI assistant uses this service to checkout your branch in a build environment
AI assistant runs builds and tests on that branch
AI assistant reports results back to you
You make fixes based on feedback and repeat
This separates your development environment from the build/test environment that the AI uses.
Installation
git clone <this-repo-url>
cd mcp-build
pip install -e .Setup
Create or designate a directory containing your git repositories:
/path/to/build-area/
├── project-one/ # git repository
├── project-two/ # git repository
└── project-three/ # git repositoryUsage
Local mode (stdio)
Start the service in the directory containing your repositories:
cd /path/to/build-area
mcp-buildConfigure Claude Desktop to use it. Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"build": {
"command": "mcp-build",
"cwd": "/path/to/build-area"
}
}
}Remote mode (HTTP)
Start with HTTP transport:
cd /path/to/build-area
mcp-build --transport http --host 0.0.0.0 --port 3344The service generates a session key on startup. Configure Claude Desktop with:
{
"mcpServers": {
"build": {
"url": "http://your-server:3344/sse?key=SESSION_KEY"
}
}
}Command-line options
mcp-build --help # Show all options
mcp-build # stdio mode (default)
mcp-build --transport http # HTTP mode, auto-generate session key
mcp-build --transport http --session-key YOUR_KEY
mcp-build --transport http --host 0.0.0.0 --port 8080Available tools
The service exposes these MCP tools:
list - List available repositories
git - Execute git commands (limited to: status, log, checkout, pull, branch, diff, fetch, show)
make - Run make with specified arguments (executes whatever is in the Makefile)
ls - List files and directories
env - Show installed tools and versions
read_file - Read file contents (with optional line range for large files)
Security considerations
Git operations: The service restricts git commands to a whitelist (status, log, checkout, pull, branch, diff, fetch, show). Dangerous operations like git push --force or git reset --hard are blocked.
Command validation: The service blocks path traversal patterns (../) and some command injection patterns (pipes, redirects, command substitution).
Make targets: The service runs whatever make targets you specify. These execute the commands defined in the repository's Makefile, which could be anything. The service does not sandbox or restrict what Makefiles can do.
Authentication (HTTP mode): Requires a session key passed as a Bearer token or query parameter. Keys can be auto-generated or provided.
Recommendation: Run this service in an environment appropriate for build operations (e.g., a dedicated build VM, container, or CI environment). It validates some inputs but does not provide comprehensive sandboxing.
Example usage with AI assistant
Once configured, you can ask your AI assistant:
"List the available repositories"
"Checkout the feature-branch in my-project and run make test"
"What's the build output from the latest commit on main?"
"Show me the diff between main and feature-branch"
The AI will use the service automatically through MCP tool calls.
Troubleshooting
No repositories found
Verify you started mcp-build in the parent directory of your git repos
Check each directory has a
.gitsubdirectory
Repository not found
Repository names must match directory names exactly
Use the list tool to see available names
Build failures
Use the env tool to check installed build tools
Verify the Makefile exists and has the target you're trying to run
Connection issues (HTTP mode)
Check the session key matches what the service printed at startup
Verify firewall allows the port
Test with curl:
curl -H "Authorization: Bearer KEY" http://host:port/api/repos
HTTP API
In addition to the MCP protocol, the service provides HTTP endpoints:
Quick operations (REST):
GET /api/repos- List repositoriesGET /api/repos/{repo}/env- Environment infoPOST /api/repos/{repo}/ls- List filesPOST /api/repos/{repo}/read_file- Read file contentsPOST /api/repos/{repo}/git/quick- Quick git operations (status, branch, log)
Long operations (streaming SSE):
POST /stream/repos/{repo}/make- Stream build outputPOST /stream/repos/{repo}/git- Stream git operations (pull, fetch, diff, show, checkout)
All endpoints require authentication via session key.
Development
Run tests:
pip install -e ".[dev]"
pytest tests/Project structure:
mcp-build/
├── src/
│ ├── server.py # Main server
│ └── validators.py # Input validation
├── tests/ # Tests
├── README.md # This file (user docs)
└── MCP-BUILD.md # Agent usage guideLicense
MIT License
Available Tools
6 toolsenvB
Show environment information including environment variables and versions of key build tools (gcc, g++, python, make, cmake, etc.). If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Inputs: repo (required), branch.
gitA
Run git commands in a repository. Limited to safe operations: status, log, checkout, pull, branch, diff, fetch, reset, show. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Inputs: args (required), repo (required), branch.
listB
List available repositories discovered in the current directory
Inputs: no named parameters.
lsA
List files and directories in a repository. Limited to paths within the repository to prevent path traversal. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Inputs: repo (required), args, branch.
makeA
Run make command with specified arguments. Executes make in the root of the specified repository. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Inputs: repo (required), args, branch.
read_fileA
Read the contents of a file in a repository. Supports reading specific line ranges for large files. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Inputs: repo (required), path (required), start_line, end_line, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have distinct purposes: env shows environment info, git runs git commands, list shows repositories, ls lists files, make runs make, and read_file reads file contents. However, 'list' and 'ls' could potentially be confused as both involve listing, though 'list' is for repositories and 'ls' is for files within a repository, which is clarified in descriptions.
The naming is mixed: 'env', 'git', 'list', 'ls', 'make', and 'read_file' use a variety of styles. 'env', 'git', 'list', 'ls', and 'make' are simple command-like names, while 'read_file' uses snake_case. There's no consistent verb_noun pattern, but the names are generally readable and intuitive for their functions.
With 6 tools, this is well-scoped for a build environment service. Each tool serves a clear purpose in managing repositories, files, and build processes, and the count is appropriate without being too thin or bloated for the domain.
The tool set covers key operations for a build environment: environment inspection (env), repository management (git, list), file operations (ls, read_file), and build execution (make). A minor gap is the lack of tools for writing or modifying files, which might be intentional for safety but could limit some build workflows.
Related MCP Connectors
Build, test and cache insights for Xcode, Gradle and Bazel projects, for coding agents.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Rent and manage dedicated Apple Silicon Macs for iOS builds and CI/CD from your AI agent.
Run AI agent tasks in isolated sandboxes with a cost cap, saved workflows and scoped connections.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to automatically analyze GitHub repositories and set up development environments by detecting tech stacks, installing dependencies, and verifying project builds. Provides safe tools for repository cloning, file system operations, package installation, and build verification through an allowlisted command system.-
- AlicenseNot gradedqualityCmaintenanceProvides a restricted Docker-based sandbox for LLM agents, enabling file operations, command execution, and local Git within an isolated runtime.19 npmMIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to safely execute commands, run tests, and modify project files inside disposable, policy-enforced Docker sandboxes that are isolated from the host machine and its credentials.15MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to safely execute code, run tests, and build projects inside disposable Docker sandboxes, protecting the host machine through enforced isolation, filesystem snapshots, and network controls.15MIT