infrahub-mcp — Claude Code MCP server: query Infrahub data
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.
claude mcp add infrahub-mcp -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcpWhat infrahub-mcp 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.
What it helps with
- 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 for the agent
- Find every 100G interface on
edge-01in 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
How to install infrahub-mcp
Platform CLI
claude mcp add infrahub-mcp -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>
Platform CLI
codex mcp add infrahub-mcp --env INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> --env INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
gemini mcp add -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> infrahub-mcp uvx infrahub-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from infrahub-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about infrahub-mcp
How do I install infrahub-mcp in Claude Code?
Run claude mcp add infrahub-mcp -e INFRAHUB_ADDRESS=<INFRAHUB_ADDRESS> -e INFRAHUB_API_TOKEN=<INFRAHUB_API_TOKEN> -- uvx infrahub-mcp. Replace the placeholders with your Infrahub address and API token.
What does infrahub-mcp do?
It links an AI assistant to Infrahub over MCP: the agent queries infrastructure data, reads the schema, and can propose edits. Changes go to a separate branch and need approval before merging.
What does infrahub-mcp need to run?
An Infrahub instance address and an API token, passed as INFRAHUB_ADDRESS and INFRAHUB_API_TOKEN. It runs over stdio or streamable HTTP.
