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.
What you get
73 MCP tools for controlling Gephi Desktop — graph construction, community detection, centrality analysis, layout algorithms, filtering, styling, and publication-ready export.
Claude Code plugin with slash commands (/analyze-network, /community-detection, /centrality, /visualize, /import-and-explore), a specialized network analyst agent, and workflow skills that teach Claude network science best practices.
Works with any MCP client — Claude Code, Claude Desktop, or any MCP-compatible assistant.
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 73 Gephi tools via MCP |
| Claude Plugin | claude-plugin/ | Skills, commands, agent, and hooks for Claude Code |
All three must be installed. Gephi Desktop must be running before using any tools.
Setup
Prerequisites
Step 1: Install the Gephi plugin
This adds the HTTP API server inside Gephi Desktop.
cd gephi-mcp-plugin
mvn clean package
Then in Gephi: Tools → Plugins → Downloaded → Add Plugins — select target/nbm/gephi-mcp-1.0.0.nbm.
Restart Gephi. The plugin starts automatically and listens on http://127.0.0.1:8080.
Verify: Open a browser to http://127.0.0.1:8080/health — you should see {"success": true}.
Step 2: Install the MCP server
This bridges MCP clients to the Gephi HTTP API.
cd mcp-server
pip install -e .
This installs the gephi-mcp command on your PATH.
Verify: Run gephi-mcp --help to confirm it installed.
Step 3: Connect your AI assistant
Claude Code (full plugin — recommended)
claude plugin install gephi-ai/gephi-network-analysis
This adds the MCP server, slash commands, network analyst agent, skills, and a health-check hook.
Claude Code (MCP tools only)
If you just want the 73 tools without skills and commands:
claude mcp add gephi-mcp -- gephi-mcp
Claude Desktop
Add to your MCP configuration (claude_desktop_config.json):
{
"mcpServers": {
"gephi-mcp": {
"command": "gephi-mcp"
}
}
}
Other MCP clients
Point your client at the gephi-mcp command using stdio transport.
Step 4: Verify
With Gephi running, ask your assistant:
"Check if Gephi is running"
It should call gephi_health_check and confirm the connection. In Claude Code, try:
/gephi-network-analysis:import-and-explore path/to/your/graph.gexf
What the Claude Code plugin adds
The plugin (claude-plugin/) goes beyond raw MCP tools:
| Component | What it does |
|---|
| Slash commands | /analyze-network, /community-detection, /centrality, /visualize, /import-and-explore |
| Network analyst agent | Specialized subagent for deep structural analysis, metric comparison, and network classification |
| Gephi skill | Teaches Claude network science workflows, visualization best practices, and known Gephi gotchas |
| Health-check hook | Automatically verifies Gephi is running before graph-modifying operations |
| Reference guides | Tool reference, layout guide, and statistics interpretation guide |
Tools (73)
