gobject-introspection-mcp

An MCP server that exposes GObject Introspection metadata to coding agents. It parses the .gir XML files installed on your system and makes every library, class, function, signal, property, enum member, and struct field queryable through a standard set of MCP tools.

All data is C-language-oriented: C symbol names, C type strings, header includes, ownership-transfer semantics (none / container / full), argument directions (in / out / inout), and GType information.

A SQLite cache (~/.cache/gi-mcp/cache.db) is maintained automatically. Each namespace is re-parsed only when its .gir file changes on disk.

Requirements

• Python 3.11+
• lxml (usually already installed system-wide)
• GIR files — install the -dev / -devel packages for the libraries you want to introspect, e.g. libgtk-4-dev, libglib2.0-dev

Running

With uv (no install required)

# stdio transport — used by Claude Code and VS Code Copilot
uv run --project /path/to/gobject-introspection-mcp gi-mcp

# streamable-HTTP transport (for remote/browser clients)
uv run --project /path/to/gobject-introspection-mcp gi-mcp --transport http --port 8000

Installed via pip

pip install --user .
gi-mcp                          # stdio (default)
gi-mcp --transport http --port 8000

Editor integration

VS Code Copilot

Add to .vscode/mcp.json in your workspace (a ready-made file is included):

{
  "servers": {
    "gi": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${workspaceFolder}", "gi-mcp"]
    }
  }
}

Claude Code

Add to .claude/settings.json in your project (a ready-made file is included):

{
  "mcpServers": {
    "gi": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/gobject-introspection-mcp", "gi-mcp"]
    }
  }
}

Switch to Agent mode in Copilot Chat, or start a Claude Code session — the tools listed below will be available automatically.

MCP tools

Tool	Description
list_namespaces	All installed GIR namespaces with version, shared library, C prefixes, headers, and dependencies
list_symbols(namespace, [version], [kind])	All top-level symbols in a namespace; filter by kind ("class", "function", "enumeration", …)
search_symbols(query, [max_results])	Case-insensitive name substring search across all namespaces
search_by_c_identifier(c_identifier, [max_results])	Find symbols by C name (e.g. gtk_widget_show, GTK_ALIGN_FILL)
get_symbol_details(namespace, name, [version])	Full details for any top-level symbol — C type, methods, properties, signals, fields, parent, interfaces, headers
list_members(namespace, symbol_name, [version])	Methods, constructors, properties, signals, and fields of a class, interface, record, or union
get_inheritance_chain(namespace, symbol_name, [version])	Full ancestor chain from a class to the root, including which interfaces each ancestor implements
find_implementations(namespace, interface_name, [version])	All classes across all namespaces that implement an interface
get_signal(namespace, symbol_name, signal_name, [version])	Full signal details: parameters with types and transfer ownership, emission timing, flags, doc
get_property(namespace, symbol_name, property_name, [version])	Property type, C type, read/write/construct flags, transfer ownership, doc
get_field(namespace, symbol_name, field_name, [version])	Struct/record/union field: type, C type, pointer flag, readable/writable, doc
get_enum_member(namespace, symbol_name, member_name, [version])	Enum or flags member: integer value, C macro name (e.g. GTK_ALIGN_FILL), doc
get_callback(namespace, name, [version])	Callback typedef: full parameter list with directions and transfer, return type, GError flag
search_signals(query, [namespace], [max_results])	Find signals by name substring — answers "which class emits clicked?"
search_properties(query, [namespace], [max_results])	Find properties by name substring across all types
get_constant(namespace, name, [version])	Top-level constant: value, C macro name, type, headers
list_deprecated(namespace, [version], [kind])	All deprecated symbols in a namespace, optionally filtered by kind

Example queries

list_namespaces
→ [{namespace: "GLib", version: "2.0", headers: ["glib.h"], ...}, ...]

get_symbol_details("GObject", "Object")
→ {name: "Object", c_type: "GObject", gtype_name: "GObject",
   headers: ["glib-object.h"], methods: [...], signals: [...], ...}

get_signal("GObject", "Object", "notify")
→ {name: "notify", when: "first", callable: {parameters: [{name: "pspec", ...}]}}

search_signals("clicked")
→ [{signal_name: "clicked", defined_on: "Button", namespace: "Gtk", ...}, ...]

get_enum_member("Gtk", "Align", "fill")
→ {name: "fill", value: 0, c_identifier: "GTK_ALIGN_FILL", kind: "enumeration"}

search_by_c_identifier("g_object_ref")
→ [{c_identifier: "g_object_ref", name: "ref", kind: "method",
    defined_on: "Object", namespace: "GObject"}]

get_inheritance_chain("Gtk", "Button")
→ {name: "Button", parent: "Gtk.Widget", implements: ["Gtk.Actionable", ...],
   ancestors: [{name: "Widget", ...}, {name: "Object", namespace: "GObject"}]}

Cache

Parsed data is stored in $XDG_CACHE_HOME/gi-mcp/cache.db (default ~/.cache/gi-mcp/cache.db). Each namespace is a set of rows in a SQLite database — one row for namespace metadata and one row per symbol — keyed by namespace name and the .gir file's modification time. Stale entries are replaced automatically; no manual cache management is needed.

Override the cache location via XDG_CACHE_HOME. Override which .gir directories are searched via GIR_PATH (colon-separated).