Installing Infrahub MCP

This guide provides step-by-step instructions for installing and configuring different MCP clients to connect to the Infrahub MCP server.

For container-based deployments (Docker Compose, sidecar alongside Infrahub), see the Docker deployment guide. To run the server in Kubernetes next to an Infrahub instance installed with Helm, see Deploy on Kubernetes with Helm.

Prerequisites

• Python 3.13+
• Access to an Infrahub instance
• An API token or credentials for your Infrahub instance

Install the Infrahub MCP server

uvx (recommended)

No installation needed — uvx runs the package directly from PyPI:

uvx infrahub-mcp --help

note

The infrahub-mcp CLI entry point requires version 1.1.0 or later. For earlier versions, use uvx --from infrahub-mcp fastmcp run infrahub_mcp.server:mcp instead.

pip / uv pip

pip install infrahub-mcp
# or
uv pip install infrahub-mcp

Docker

docker pull registry.opsmill.io/opsmill/infrahub-mcp:latest

See the Docker deployment guide for Docker Compose and sidecar setups.

From source (development)

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

Run the server

# With uvx (no install)
uvx infrahub-mcp

# Or if installed via pip
infrahub-mcp

# With explicit transport
infrahub-mcp --transport streamable-http --host 0.0.0.0 --port 8001

Configuration

Set the following environment variables as needed:

Variable	Description	Default
INFRAHUB_ADDRESS	URL of your Infrahub instance	required
INFRAHUB_API_TOKEN	API token (or use username + password)	—
MCP_HOST	Host for the web server	0.0.0.0
MCP_PORT	Port for the web server	8001
INFRAHUB_MCP_READ_ONLY	Disable write operations	false
INFRAHUB_MCP_LOG_LEVEL	Set to debug for verbose logging	info

For the full list of configuration options (rate limiting, caching, auth, observability), see the Configuration reference.

Add to your MCP client

Cursor

Go to Settings > Cursor Settings > Tools & Integrations, click Add Custom MCP, and paste the following into mcp.json:

{
  "mcpServers": {
    "infrahub_mcp": {
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000",
        "INFRAHUB_API_TOKEN": "your-api-token"
      }
    }
  }
}

For tool-approval tuning, workspace rules, and troubleshooting, see the Cursor integration guide.

VS Code

Open the MCP Servers configuration file (Cmd+Shift+P, type "MCP: Open User Configuration") and add:

{
  "servers": {
    "infrahub_mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000",
        "INFRAHUB_API_TOKEN": "your-api-token"
      }
    }
  }
}

For Copilot compatibility ($ref inlining) and troubleshooting, see the VS Code integration guide.

Claude Desktop

Go to Settings > Developer, click Edit config to open claude_desktop_config.json, and add to the mcpServers section:

{
  "mcpServers": {
    "infrahub_mcp": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000",
        "INFRAHUB_API_TOKEN": "your-api-token"
      }
    }
  }
}

For remote server setup, prompts, and troubleshooting, see the Claude Desktop integration guide.

Claude Code

Add an .mcp.json file at the root of your project (Claude Code auto-detects it on startup):

{
  "mcpServers": {
    "infrahub": {
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000",
        "INFRAHUB_API_TOKEN": "your-api-token"
      }
    }
  }
}

For CLAUDE.md conventions, bundled prompts, and troubleshooting, see the Claude Code integration guide.

Streamable HTTP with authentication

When the MCP server runs over Streamable HTTP with token-passthrough or basic-passthrough auth, clients connect via URL and pass credentials in the Authorization header instead of using stdio with env vars. See Set up authentication for server-side configuration.

warning

These configuration files contain credentials in plain text. Do not commit them to version control — add .mcp.json to .gitignore.

Claude Code

In your .mcp.json:

{
  "mcpServers": {
    "infrahub": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer <your-infrahub-api-token>"
      }
    }
  }
}

For basic passthrough, replace the Authorization value with Basic <base64(username:password)>.

Cursor

In your .cursor/mcp.json:

{
  "mcpServers": {
    "infrahub_mcp": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer <your-infrahub-api-token>"
      }
    }
  }
}

For basic passthrough, replace the Authorization value with Basic <base64(username:password)>.

Claude Desktop

In your claude_desktop_config.json:

{
  "mcpServers": {
    "infrahub_mcp": {
      "transport": "streamable-http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer <your-infrahub-api-token>"
      }
    }
  }
}

For basic passthrough, replace the Authorization value with Basic <base64(username:password)>.

VS Code

In your .vscode/mcp.json:

{
  "servers": {
    "infrahub_mcp": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer <your-infrahub-api-token>"
      }
    }
  }
}

For basic passthrough, replace the Authorization value with Basic <base64(username:password)>.

Related resources