MCP Builder Toolkit

Manifest-driven CLI that generates readable, tested Python MCP server projects with safe regeneration and optional Docker/CI assets.

MCP defines the protocol. MCP Builder Toolkit defines a repeatable way to create, inspect, test, and package an MCP server.

Status: v0.1.0a4 published. Alpha software, not production-ready. Version: derived from the latest git tag via hatch-vcs.

What the YAML controls

The manifest declares project-generation intent:

• FastMCP Python compatibility profile and MCP protocol version;
• stdio or Streamable HTTP transport;
• package name and supported Python range;
• tests, linting, typing, Docker, Compose, GitHub Actions, and structured logs;
• whether to include the replaceable example tool.

Tool behavior and API integrations remain normal, user-owned Python code. The alpha does not generate arbitrary tools from YAML or convert OpenAPI documents. See YAML capabilities and boundaries for the complete boundary and an API integration example.

Install

uv tool install mcp-builder-toolkit
mcp-builder --version

From a source checkout:

uv sync --all-extras
uv run mcp-builder --version

Guided quickstart (recommended)

Full walkthrough (generate → implement tools → test → call with a real MCP client):

→ Guided quickstart

Short path

mkdir -p ~/dev/my-mcp && cd ~/dev/my-mcp
mcp-builder init --name my-mcp --transport stdio --no-interactive
mcp-builder validate
mcp-builder generate

uv sync --all-extras
uv run pytest
uv run python -m my_mcp.server

Streamable HTTP + Docker: see the guided quickstart (Step 12) or set transport.type: streamable-http and features.docker/compose: true, then mcp-builder generate.

For generated containers, the server binds to 0.0.0.0 inside the container while Compose preserves the manifest's conservative host-side publication (default 127.0.0.1).

Commands

Architecture

manifest.yaml
    → parse + validate + normalize
    → protocol-independent ProjectSpec
    → FastMCP adapter + Docker/Compose/CI features
    → ArtifactPlan (managed / scaffold-once / derived)
    → locked staged apply + .mcp-builder/state.json

Generated projects do not depend on this builder at runtime.

Compatibility profile

Development

uv sync --all-extras
uv run ruff check src tests
uv run mypy src
uv run pytest
# optional: pre-commit install

Update golden trees after intentional template changes:

uv run python scripts/update_golden.py

Documentation

Explicit v0.1 boundary

Not in this release: OAuth, policy engines, budgets, audit receipts, A2A, agent contracts, gateways, multi-language generation, hosted control plane.

License

Apache-2.0