Skip to main content

Install the Infrahub MCP server

This guide gets you from a fresh checkout to a running Infrahub MCP server in a few minutes. Once it's running, continue with Authentication to pick a credential model, then Your first agent run to connect an LLM.

For a containerized deployment (Docker Compose, sidecar alongside Infrahub), see the Docker Compose guide.

Prerequisites​

  • Python 3.13 or newer
  • uv for dependency management
  • An Infrahub instance you can reach over HTTP
  • An Infrahub API token (create one from Admin → API tokens in the Infrahub UI)

Install​

The recommended way is via uvx (no clone needed):

uvx infrahub-mcp --help

Or install into an existing environment:

pip install infrahub-mcp

To develop or contribute, clone the repository:

git clone https://github.com/opsmill/infrahub-mcp.git
cd infrahub-mcp
uv sync

Configure the connection​

The server reads its configuration from environment variables. At minimum, set the Infrahub URL and an API token:

export INFRAHUB_ADDRESS=http://localhost:8000
export INFRAHUB_API_TOKEN=06438eb2-8019-4776-878c-0941b1f1d1ec

For the complete list of variables (rate limiting, caching, observability, auth), see the Configuration reference.

Run the server​

Stdio transport (local clients)​

Stdio is the default transport for MCP clients that spawn the server as a subprocess (Claude Desktop, Claude Code with .mcp.json):

uvx infrahub-mcp

Streamable HTTP transport (remote clients, Docker)​

HTTP is required for token pass-through, OIDC, or any client connecting over the network:

uvx infrahub-mcp --transport streamable-http --host 0.0.0.0 --port 8001

The server exposes three endpoints on the configured port:

PathDescription
/mcpMCP Streamable HTTP transport
/healthHealth probe — returns {"status": "healthy"} or HTTP 503
/metricsRequest counts, errors, latency (JSON or Prometheus format)

Verify it is running​

With the HTTP transport:

curl -s http://localhost:8001/health
# {"status":"healthy"}

Or inspect the server logs — you should see a line confirming the Infrahub connection and the middleware stack that is active.

Next steps​