infrahub-mcp
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@infrahub-mcp list all devices in the 'production' location"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Infrahub MCP Server
Infrahub MCP Server connects AI assistants and IDE agents to Infrahub using the open Model Context Protocol standard — so agents can query, create, update, and propose changes to your infrastructure data through a consistent, audited interface. It works with any MCP-compatible client (Claude Desktop, VS Code, Cursor, CLI agents, and more) with no custom glue code required.
All writes are branch-isolated and require human approval before merging — agents never modify your default branch directly.
Installation
pip install infrahub-mcp
# or
uv pip install infrahub-mcpDocker:
docker pull registry.opsmill.io/opsmill/infrahub-mcp:latest
# or use Docker Compose:
docker compose up -dRelated MCP server: python-openstackmcp-server
Quickstart
Point the server at your Infrahub instance via environment variables, then run it over the transport your client expects.
stdio (default — for Claude Desktop, VS Code, Cursor):
export INFRAHUB_ADDRESS=http://localhost:8000
export INFRAHUB_API_TOKEN=<your-token>
infrahub-mcpStreamable HTTP (for remote clients, sidecar deployments):
infrahub-mcp --transport streamable-http --host 0.0.0.0 --port 8001What you can do with it
Query your infrastructure data from natural language — find devices, interfaces, IP addresses, or any kind in your schema, with attribute filtering and partial-match search.
Explore your schema without leaving the conversation — the server exposes your catalog, per-kind attribute/filter maps, and the GraphQL SDL as MCP resources.
Make changes on isolated branches — writes land on an auto-created session branch (
mcp/session-YYYYMMDD-<hex>); the default branch is never touched directly.Submit changes for human review — call
propose_changesto open a Proposed Change for approval before merging.Run arbitrary GraphQL — execute any query or mutation against the Infrahub API when you need full control.
Documentation
Full documentation, including client configuration for Cursor, VS Code, Claude Desktop, and Claude Code, is available at the Infrahub MCP Server docs site.
About Infrahub
Infrahub is an open source infrastructure data management and automation platform (AGPLv3), developed by OpsMill. It gives infrastructure and network teams a unified, schema-driven source of truth — devices, topology, IP space, configuration — with built-in version control, a generator framework for automation, and native integrations with Git, Ansible, Terraform, and CI/CD pipelines.
License
Apache 2.0 — see LICENSE.
Available Tools
12 toolsfind_pathsFind PathsARead-only
Find the shortest path(s) between two nodes in the Infrahub graph.
Use this to answer "how are these two objects connected?". A result with
count of 0 means no path exists within max_depth. Requires Infrahub 1.10+.
Inputs: source (required), destination (required), branch, max_depth, +2 more.
find_reachableFind ReachableARead-only
Find nodes of the given kinds reachable from a source node (impact analysis).
Use this to answer "what depends on / is connected to this object?" — for blast-radius and dependency discovery. Requires Infrahub 1.10+.
Inputs: source (required), target_kinds (required), branch, max_depth, +2 more.
get_nodesGet NodesARead-only
List nodes of a specific kind — the default read path for typed queries with optional filtering and pagination.
Prefer this over query_graphql when you just need objects of one kind:
results come back as display labels (fast, token-cheap) or full attribute
dicts (include_attributes=True).
To discover available kinds, read the infrahub://schema resource.
If your client does not support MCP resources, call the get_schema tool instead.
To discover available filters for a kind, read infrahub://schema/{kind}
or call get_schema(kind='...').
Filter keys follow the schema's filter map. Attribute filters use
<attr>__value (e.g. {"name__value": "atl1"}) and relationship
filters chain via <rel>__<attr>__value (e.g.
{"site__name__value": "atl1"}). See infrahub://schema/{kind} for
the full list of valid keys.
Use offset and limit to page through large result sets. The response
always includes total_count and has_more so you know when to stop.
Inputs: kind (required), limit, branch, offset, +3 more.
get_schemaGet SchemaARead-only
Discover available schema kinds — call this first when you don't know what kinds or filters exist.
Without a kind, returns the catalog of all kinds (compact JSON).
With a kind, returns its attributes, relationships, and the full set
of filter keys accepted by get_nodes (TOON-encoded for token efficiency).
Each relationship inlines one level of its peer schema unless expand is
False (or the server default disables it).
Prefer reading the infrahub://schema resource if your client supports
MCP resources — this tool provides the same data for clients that don't.
Inputs: kind, branch, expand.
get_session_infoGet Session InfoARead-only
Return the current MCP session state — call before writes to know which branch they target.
Reports the active session branch (if any) and the Infrahub instance address.
A session branch is lazily auto-created on the first write tool call
(node_upsert / node_delete / mutate_graphql) and is named
mcp/session-YYYYMMDD-<hex>. Before that first write, session_branch
is None and all read tools target the default branch.
Typical uses:
Confirm which branch a proposed change would merge from.
Decide whether a write is about to open a new session branch.
Display the active branch to the user.
Inputs: no named parameters.
mutate_graphqlMutate GraphqlADestructive
Execute a GraphQL mutation against Infrahub — use only for complex writes that typed tools can't express.
Prefer node_upsert (create/update scalar attributes) or node_delete
(remove a node) for straightforward changes; they validate against the
schema and produce clearer audit entries. Reach for mutate_graphql
when you need relationship edits, bulk operations, or any mutation shape
not covered by the typed tools. For reads, use query_graphql.
The mutation always runs on the active session branch (auto-created on the
first write of the session, mcp/session-YYYYMMDD-<hex>). There is no branch
override — writes are isolated to the session, and changes reach the default
branch only through propose_changes and human review. To target a different
branch deliberately, switch the session with reset_session_branch first.
Branch- and schema-management mutations are rejected.
To discover available kinds and their attributes, read the infrahub://schema
resource or call the get_schema tool.
For the full GraphQL SDL, read infrahub://graphql-schema.
Inputs: query (required).
node_deleteNode DeleteADestructive
Delete a node in Infrahub on the active session branch.
The deletion is applied to the session branch only and is not visible on the
default branch until a proposed change is merged.
To discover available kinds, read the infrahub://schema resource.
If your client does not support MCP resources, call the get_schema
tool instead.
Inputs: kind (required), id, hfid.
node_upsertNode UpsertA
Create or update a node in Infrahub on the active session branch.
The session branch is auto-created on the first write of the session
(mcp/session-YYYYMMDD-<hex>). Use propose_changes to open a
review once your changes are ready.
To discover available kinds and attributes, read the infrahub://schema
resource. If your client does not support MCP resources, call the
get_schema tool instead.
Create: omit both
idandhfid.Update: supply either
idorhfidto identify the target node.
Only scalar attribute fields are accepted in data. To set relationship
fields, use mutate_graphql with an appropriate GraphQL mutation.
Inputs: data (required), kind (required), id, hfid.
propose_changesPropose ChangesA
Open a proposed change (pull request) from the active session branch to the default branch.
Creates a CoreProposedChange in Infrahub so a human can review, approve,
and merge the changes made during this session. The session branch remains
active after calling this — you can continue making changes.
Inputs: title (required), description, destination_branch.
query_graphqlQuery GraphqlARead-only
Execute a read-only GraphQL query against Infrahub — use for reads only, never mutations.
Mutations are rejected at the AST level: use mutate_graphql instead
(available when write mode is enabled). For simple attribute reads, prefer
get_nodes / search_nodes — use GraphQL only when you need relationship
traversal, aggregation, or fields not exposed by the typed tools.
To discover available kinds and their attributes, read the infrahub://schema
resource. If your client does not support MCP resources, call the get_schema
tool instead. For the full GraphQL SDL, read infrahub://graphql-schema.
Inputs: query (required), branch.
reset_session_branchReset Session BranchA
Reset or switch the active session branch for the calling client.
Use this to recover or take control of which branch your writes target:
No
branch— clears the cached session branch; the next write auto-creates a fresh one. Useful after you have merged your work and want to start a new change set.With
branch— makes the named branch the session branch. If it does not exist and the name matches the configured branch pattern, it is created and reported. The instance default branch and merged/read-only branches are rejected.
Note: a merged or deleted session branch is recovered automatically on the next write — this tool is the explicit override on top of that.
Scope: the session branch is kept per authenticated caller, and per MCP session when the client has one. Without credentials or an MCP session, all clients of the server share one session branch. A reset or switch applies to every conversation that shares the session branch.
Inputs: branch.
search_nodesSearch NodesARead-only
Find nodes of a specific kind by partial substring — use when you only know part of a value.
Matches the query as a substring against all attributes of the kind
via Infrahub's any__value filter with partial_match=True. Works
uniformly on concrete kinds (e.g. LocationSite) and abstract/generic
kinds (e.g. CoreNode) — agents can ping any kind without first
checking whether it has a name attribute.
For a filter on one specific attribute (or combining multiple filters),
use get_nodes with an explicit filters dict instead.
Each result is labelled with the node's display_label when present,
falling back to its HFID (kind-prefixed) and finally its UUID — so
generic-kind results that lack a display_label still return a
human-readable identifier rather than a bare UUID.
To discover available kinds, read the infrahub://schema resource.
If your client does not support MCP resources, call the get_schema tool instead.
Inputs: kind (required), query (required), limit, branch.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have distinct purposes: typed reads (get_nodes/search_nodes), generic GraphQL reads (query_graphql), typed writes (node_upsert/node_delete), complex writes (mutate_graphql), session management, schema discovery, and graph traversal. The main overlap is between query_graphql and the typed read tools, but the descriptions clearly guide when to prefer each, so boundaries remain workable.
Most tools follow a verb_noun pattern (get_nodes, search_nodes, get_schema, find_paths, propose_changes), but node_upsert and node_delete use resource_action ordering, and some names like reset_session_branch are more phrase-like. The set is still readable, but the mixed conventions are noticeable.
Twelve tools is well-scoped for an Infrahub server covering schema discovery, typed reads/writes, GraphQL escape hatches, sessions, proposed changes, and graph traversal. Each tool appears to earn its place without excessive surface area.
The surface covers the core lifecycle: schema discovery, typed reads and searches, create/update via upsert, delete, complex mutations, proposed changes, and session control. Relationship edits require the generic mutate_graphql escape hatch, and there is no direct merge/approve tool, but these are reasonable design choices rather than critical gaps.
Maintenance
Related MCP Connectors
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
A shared, governed brain for AI agents: versioned context with approvals, local or hosted.
Intelligent context infrastructure for AI teams: knowledge graph, sessions, tasks, documents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with GitHub repositories, issues, pull requests, and content via the Model Context Protocol.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage OpenStack cloud resources including compute, images, identity, network, and block storage via the Model Context Protocol.19Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage Prismatic integrations, components, and flows via the Model Context Protocol, supporting code-native integration development and component lifecycle.472 npm27MIT

Aribot MCPofficial
AlicenseNot gradedqualityDmaintenanceEnables security work such as threat modeling, scanning, compliance checks, and remediation through AI assistants using the Model Context Protocol.MIT