octopilot-mcp

Model Context Protocol (MCP) server for Octopilot — enables AI agents to detect, generate, build, and wire up new repositories end-to-end using the Octopilot CI/CD toolchain.

What it does

`op promote-image` is intentionally not exposed. Image promotion between environments is operationally sensitive and must only run through a GitHub Actions workflow (with audit trail, OIDC credentials, and environment protection rules). Use generate_ci_workflow to produce the workflow that handles promotion safely.

Option A — Hosted (zero install)

Connect directly to the public server at https://mcp.octopilot.app — no cloning, no Python, no pip required.

# Cursor
fastmcp install cursor https://mcp.octopilot.app --name octopilot

# Claude Desktop
fastmcp install claude https://mcp.octopilot.app --name octopilot

Available hosted tools (stateless, no local dependencies):

Need `detect_project_contexts`, `onboard_repository`, or `run_op_build`? Those tools need Docker and local filesystem access — use Option B below.

Option B — Local install (full suite)

# Clone and install
git clone https://github.com/octopilot/octopilot-mcp
cd octopilot-mcp
uv sync

Usage

Register with your IDE (one command, FastMCP 3 CLI)

Docker or Colima is the only external dependency. Most tools are pure Python; run_op_build pulls ghcr.io/octopilot/op:latest automatically with --pull always, so you always run the latest release.

# Cursor
uv run fastmcp install cursor src/octopilot_mcp/server.py --name octopilot

# Claude Desktop
uv run fastmcp install claude src/octopilot_mcp/server.py --name octopilot

Development (hot-reload)

uv run fastmcp dev src/octopilot_mcp/server.py --reload

Inspect tools from the terminal

# List all available tools
uv run fastmcp list src/octopilot_mcp/server.py

# Call a tool directly
uv run fastmcp call src/octopilot_mcp/server.py tool_list_actions

Run as a server directly

uv run octopilot-mcp

Manual JSON config (alternative to fastmcp install)

{
  "mcpServers": {
    "octopilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"]
    }
  }
}

Pin to a specific op release (optional):

{
  "mcpServers": {
    "octopilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/octopilot-mcp", "octopilot-mcp"],
      "env": { "OP_IMAGE": "ghcr.io/octopilot/op:v1.0.0" }
    }
  }
}

Environment variables

Example agent interaction

User: Onboard this Rust API project to use Octopilot CI.

Agent: [calls onboard_repository("/path/to/my-api", "ghcr.io/my-org")]
       → Detected: rust (stable) in api/
       → Generated: skaffold.yaml, .github/workflows/ci.yml
       → Next steps: add .pre-commit-config.yaml, push changes

Development

uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src/octopilot_mcp --cov-report=term-missing

Tool module coverage target: ≥95% (actions, detect, generate, op_runner). See CONTRIBUTING.md for details.

Resources

The server also exposes MCP resources for agent context:

• octopilot://actions — Full actions registry JSON
• octopilot://pipeline-context-schema — JSON Schema for pipeline-context
• octopilot://docs/getting-started — Plain-text onboarding guide
• octopilot://docs/skaffold-patterns — Common skaffold.yaml patterns