gephi-network-analysis

Gephi AI

AI-powered network analysis through Gephi and the Model Context Protocol (MCP). Build, analyze, style, and export publication-ready network visualizations by talking to your AI assistant.

Built for researchers working across network science and AI.

Status: public beta. APIs may change between minor versions.

What you get

Your AI assistant drives Gephi. Say what you want in plain language and the assistant builds, analyzes, styles, and exports publication-ready network maps.

It's a conversation, not a command line. The assistant explains what it's doing, checks its own maps before showing them, and teaches you to read what you're seeing. You can point back: select nodes in the Gephi window and ask "what did I select?"

Any data, any MCP client. Network files import directly; spreadsheets and other data become networks conversationally. Works with Claude Code, Claude Desktop, or any MCP-compatible assistant.

Full feature list

• 104 tools covering the whole workflow: build, analyze, style, lay out, filter, and export
• One-level undo: destructive operations snapshot the workspace automatically, so gephi_undo brings the graph back
• Layout quality is measured, not eyeballed: the graph profile flags heavy-tailed weights and hub-and-spoke wiring before a layout runs, visual QA scores how well communities separated and frames exports around the main cloud (ignoring runaway outlier nodes), and numerically exploded layouts are caught automatically instead of exported
• Interactive network view inside the chat (pan, zoom, hover, click a node to ask about it)
• Slash commands for common jobs: /analyze-network, /community-detection, /centrality, /visualize, /import-and-explore, /beautify, /verify-claim, /text-network, /teach, /counterfactual
• Specialized agents that run multi-step work in their own context and hand back just the result: independent claim verification, layout iteration, structural analysis, and text-network construction
• Two extra layouts beyond Gephi's own: by role played in the network, and by community (best for reply and retweet networks)
• Reads your selection in the Gephi window, so "what did I select?" just works
• Drives any layout or metric plugin installed from the Gephi plugin portal
• Imports GEXF, GraphML, GML, CSV, DOT, and Pajek; turns spreadsheets and other files into networks conversationally

Architecture

Three components connect your AI assistant to Gephi Desktop:

Claude / AI Assistant
        │
   MCP Protocol (stdio)
        │
   MCP Server (Python)          ← Translates MCP tool calls to HTTP
        │
   HTTP API (localhost:8080)
        │
   Gephi Plugin (Java)          ← Runs inside Gephi Desktop
        │
   Gephi Desktop                ← Must be running first

Component	Directory	What it does
Gephi Plugin	gephi-mcp-plugin/	Java module that adds an HTTP API to Gephi Desktop
MCP Server	mcp-server/	Python server that exposes 104 Gephi tools via MCP
Claude Plugin	claude-plugin/	Skills, commands, agent, and hooks for Claude Code

Install the Gephi plugin plus your AI client's connection — the Claude Code plugin bundles the MCP server, so most users install just two things. Gephi Desktop must be running before using any tools.

Security note: the plugin's HTTP API binds to 127.0.0.1 only, validates the request Host header (DNS-rebinding defense), and sends no CORS headers — it is reachable only by local processes such as the MCP server, never by a web page. It is not authenticated, so do not expose port 8080 beyond localhost.

macOS note: older plugin versions could wedge Gephi during sustained writes against a large rendered graph (calls hang; only gephi_health_check answers). Plugin 1.2.0 fixes the two causes on our side: writes now pause the renderer via Gephi's own viz-engine API, and a read-lock leak in the query endpoints (the main culprit) is closed. All lock waits are bounded, so a genuinely wedged Gephi returns an immediate "fully quit and reopen Gephi" error instead of hanging, and gephi_health_check exposes lock probes (graph_lock, graph_lock_stats) that detect the condition. If you ever see persistent "Graph is busy" errors, restart Gephi — and make sure you are on plugin 1.2.2 or newer.

Setup

Prerequisites

• Gephi Desktop 0.11.1+
• uv (runs the MCP server; one-line install, manages Python for you)
• Claude Code or Claude Desktop (for AI interaction)

Step 1: Install the Gephi plugin

This adds the HTTP API server inside Gephi Desktop. No build tools needed — download the pre-built plugin: