gephi-ai

gephi-ai

MCP server that bridges any Model Context Protocol client to a running Gephi Desktop instance, exposing 120 tools for graph construction, statistics, community detection, layout, styling, filtering, and publication-ready export.

It translates MCP tool calls into HTTP requests against the Gephi AI plugin's local API (http://127.0.0.1:8080). Each tool has a typed signature, so clients receive a precise per-field JSON schema rather than an opaque blob.

This is the MCP server component of gephi-ai; see the top-level repository for the Gephi plugin, the Claude Code plugin, and full docs.

Install

No install needed with uv — point your MCP client at:

uvx gephi-ai

uvx fetches gephi-ai from PyPI on first run and caches it. For a persistent gephi-ai command on your PATH instead, use pipx install gephi-ai (or pipx install . from this directory). Avoid plain pip install -e . inside a virtual environment: the command is then only visible on that venv's PATH, and MCP clients launched outside your shell won't find it.

Use

The Gephi AI plugin must be installed and Gephi Desktop running first. Then point any MCP client at the gephi-ai command, e.g. for Claude Desktop:

{ "mcpServers": { "gephi-ai": { "command": "uvx", "args": ["gephi-ai"] } } }

Configuration

Env var	Default	Purpose
GEPHI_API_URL	http://127.0.0.1:8080	Gephi plugin HTTP API base URL
GEPHI_REQUEST_TIMEOUT	60.0	Per-request timeout (seconds)
GEPHI_DUPLICATE_GRACE	30	Seconds to keep checking for a workspace copy after a duplicate timed out, so a copy Gephi makes late is still removed

Graph-changing tools run one at a time within one server process, so parallel tool calls from a host cannot interleave their changes. gephi_profile_graph waits in that same queue, because it writes statistic columns, and so do the exports and gephi_visual_qa, so an image never comes from a workspace copy. Read-only tools do not wait for graph changes, and gephi_session_receipt and gephi_claim_record behave like read-only tools. Read-only tools wait until a what-if finishes, then read the original graph; this includes any time the what-if spends on slow metrics or waiting for a late copy. gephi_compare_workspaces also holds back reads while it runs, because it switches between the two workspaces. A what-if or a compare waits for reads already in progress before it starts. After a workspace duplicate times out, the server may keep checking for the late copy for up to GEPHI_DUPLICATE_GRACE seconds before it answers.

Development

pip install -e ".[dev]"
ruff check .
mypy ./*.py gephi_mcp_viewer
python -m pytest -q --cov   # fails below the coverage floor in pyproject.toml

License

Apache-2.0 — see the repository LICENSE.