# infrahub-mcp

Wires your AI assistant into Infrahub so it can look up devices, interfaces and IP addresses from a plain-language request. Writes stay on a side branch until someone approves them.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10
- Author: opsmill
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/opsmill/infrahub-mcp
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/infrahub-mcp

## What it does

The server hands an agent access to your Infrahub instance. It searches devices, interfaces and IP addresses with attribute filters and partial matching, and exposes your catalog, per-kind attribute and filter maps, plus the GraphQL SDL as MCP resources. When the built-in tools are not enough, you can run any GraphQL query or mutation against the API.

Writes never land on your default branch. The server creates a session branch named `mcp/session-YYYYMMDD-<hex>`, and merging goes through `propose_changes`, which opens a Proposed Change for a human to review. That matters if agents touch topology or IP space in your setup.

Set `INFRAHUB_ADDRESS` and `INFRAHUB_API_TOKEN` before you start — the server cannot reach the instance without them. stdio is the default transport; remote clients can use streamable HTTP via `--transport streamable-http --host 0.0.0.0 --port 8001`. Install with `pip install infrahub-mcp` or `uv pip install infrahub-mcp`, or pull `registry.opsmill.io/opsmill/infrahub-mcp:latest`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `INFRAHUB_ADDRESS`, `INFRAHUB_API_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add infrahub-mcp -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add infrahub-mcp --env INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> --env INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "infrahub-mcp": {
            "command": "uvx",
            "args": [
                "infrahub-mcp"
            ],
            "env": {
                "INFRAHUB_ADDRESS": "<INFRAHUB_ADDRESS>",
                "INFRAHUB_API_TOKEN": "<INFRAHUB_API_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "infrahub-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "infrahub-mcp"
            ],
            "env": {
                "INFRAHUB_ADDRESS": "<INFRAHUB_ADDRESS>",
                "INFRAHUB_API_TOKEN": "<INFRAHUB_API_TOKEN>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> infrahub-mcp uvx infrahub-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>

## When to use it
- find a device or interface by partial name inside the chat
- inspect the Infrahub schema and available filters without leaving the editor
- stage topology edits on an isolated branch
- send changes for review as a Proposed Change
- run a custom GraphQL query against the Infrahub API

## Example prompts
- Find every 100G interface on `edge-01` in Infrahub
- Create a new IP prefix on a session branch and propose the change for review
- Show me the schema for the device kind and its filters

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md