Skip to main content
Glama

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-mcp

Docker:

docker pull registry.opsmill.io/opsmill/infrahub-mcp:latest
# or use Docker Compose:
docker compose up -d

Related 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-mcp

Streamable HTTP (for remote clients, sidecar deployments):

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

What 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_changes to 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 tools
find_pathsFind PathsA
Read-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 ReachableA
Read-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 NodesA
Read-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 SchemaA
Read-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 InfoA
Read-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 GraphqlA
Destructive

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 DeleteA
Destructive

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 id and hfid.

  • Update: supply either id or hfid to 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 GraphqlA
Read-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 NodesA
Read-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

    A4.1/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with GitHub repositories, issues, pull requests, and content via the Model Context Protocol.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to manage Prismatic integrations, components, and flows via the Model Context Protocol, supporting code-native integration development and component lifecycle.
      472 npm
      27
      MIT