Gephi MCP

Controle o Gephi Desktop pelo seu assistente de IA com 80 ferramentas para construir, analisar, organizar e estilizar grafos de rede, além de um visualizador interativo de grafos dentro do chat.

GitHub

Documentação

Gephi AI

Controle o Gephi conversando com seu assistente de IA. Construa, analise, estilize e exporte mapas de rede prontos para publicação por meio do Model Context Protocol (MCP).

Feito para pesquisadores que trabalham na interseção entre ciência de redes e IA.

Status: beta público. As APIs podem mudar entre versões menores.

O que você obtém

Seu assistente de IA controla o Gephi. Diga o que você quer em linguagem simples e o assistente constrói, analisa, estiliza e exporta o mapa.

É uma conversa, não uma linha de comando. O assistente explica o que está fazendo, verifica seus próprios mapas antes de mostrá-los e ensina você a ler o que vê. Você pode apontar de volta: selecione nós no Gephi e pergunte "o que eu selecionei?"

Qualquer dado, qualquer cliente MCP. Arquivos de rede são importados diretamente, e planilhas e outros dados se tornam redes por meio de conversa. Funciona com Claude Code, Claude Desktop, OpenAI Codex, Gemini CLI ou qualquer cliente MCP.

Lista completa de recursos

120 ferramentas cobrindo todo o fluxo de trabalho: construir, analisar, estilizar, organizar, filtrar e exportar
Desfazer de um nível: operações destrutivas criam um snapshot do espaço de trabalho primeiro, então gephi_undo traz o grafo de volta
Qualidade de layout medida: o perfil do grafo sinaliza pesos de cauda pesada e conexões hub-and-spoke antes de um layout ser executado, a QA visual avalia quão bem as comunidades se separam, e layouts numericamente explodidos são detectados em vez de exportados
Visualização interativa da rede dentro do chat (pan, zoom, passar o mouse e clicar em um nó para perguntar sobre ele)
Comandos de barra para tarefas comuns: /analyze-network, /community-detection, /centrality, /visualize, /export-map, /import-and-explore, /explore, /verify-claim, /text-network, /teach e /counterfactual
Agentes especializados para verificação de alegações, iteração de layout, análise estrutural e redes de texto
Dois layouts extras além dos do próprio Gephi: por papel na rede e por comunidade
Lê sua seleção na janela do Gephi
Controla qualquer plugin de layout ou métrica instalado a partir do portal de plugins do Gephi
Importa GEXF, GraphML, GML, CSV, DOT e Pajek

Instalação

Você precisa do Gephi Desktop 0.11.3 ou mais recente e de um assistente de IA. A maioria dos clientes também precisa do uv, que executa o servidor e gerencia o Python para você; o Claude Desktop traz o seu próprio.

1. Adicione o plugin ao Gephi

Baixe o gephi-ai-1.5.2.nbm na página de Releases.
No Gephi, abra Ferramentas > Plugins > Baixados > Adicionar Plugins, selecione o arquivo e clique em Instalar.
Reinicie o Gephi. Ferramentas > Gephi AI Server mostra que o plugin está em execução.

2. Conecte seu assistente

Use um método de conexão por aplicativo. Dois ao mesmo tempo significam dois servidores e todas as ferramentas listadas duas vezes.

Claude Code (recomendado: adiciona os comandos de barra, agentes e habilidades):

claude plugin marketplace add MattArtzAnthro/gephi-ai
claude plugin install gephi-network-analysis@gephi-ai

Claude Desktop: baixe o gephi-ai-<version>.mcpb na página de Releases e clique duas vezes nele. O Claude Desktop instala Python, o servidor e suas dependências por conta própria. O primeiro lançamento precisa de conexão com a internet e pode levar um minuto. Testado com Claude Desktop 1.40609.0.

OpenAI Codex (adiciona os mesmos fluxos de trabalho como habilidades):

codex plugin marketplace add MattArtzAnthro/gephi-ai --ref main
codex plugin add gephi-network-analysis@gephi-ai

Inicie uma nova tarefa no Codex após a instalação.

Gemini CLI:

gemini mcp add -s user gephi-ai uvx gephi-ai

Qualquer outro cliente MCP: execute uvx gephi-ai via stdio.

Somente ferramentas, sem as habilidades e comandos

claude mcp add gephi-ai -- uvx gephi-ai
codex mcp add gephi-ai -- uvx gephi-ai

Claude Desktop por meio do arquivo de configuração (claude_desktop_config.json):

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

Orientação de análise de rede para outros agentes

Copie a pasta de habilidades para o diretório de habilidades do seu agente:

git clone https://github.com/MattArtzAnthro/gephi-ai.git
cp -r gephi-ai/plugins/claude-code/skills/gephi ~/.codex/skills/

Agente	Diretório de habilidades
OpenAI Codex	`~/.codex/skills/` (ou instale o plugin do Codex acima)
Cursor	`~/.cursor/skills/`
GitHub Copilot / VS Code	`~/.copilot/skills/`
Qualquer agente, por projeto	`.agents/skills/` no seu repositório

O repositório também contém AGENTS.md e GEMINI.md, que esses agentes leem por conta própria.

3. Verifique se funciona

Com o Gephi aberto, pergunte ao seu assistente: "Verifique se o Gephi está em execução." Ele deve chamar gephi_health_check e confirmar a conexão, incluindo se o seu plugin e servidor estão atualizados.

Atualização

A verificação de saúde informa uma vez por sessão quando algo está desatualizado.

Claude Code: claude plugin update gephi-network-analysis@gephi-ai, depois inicie uma nova sessão.
Pacote do Claude Desktop: baixe o .mcpb mais recente em Releases e clique duas vezes nele.
Arquivo de configuração ou setups com uvx: nada a fazer; uvx busca a versão mais recente quando o aplicativo reinicia.
Plugin do Gephi: instale o .nbm mais recente por meio de Ferramentas > Plugins > Baixados e reinicie o Gephi.

Notas de atualização

Do plugin 1.2.x (uma vez): o plugin foi renomeado para Gephi AI, então a nova versão instala ao lado da antiga e ambas tentam usar a porta 8080. Em Ferramentas > Plugins > Instalados, desinstale o Gephi AI (MCP), reinicie o Gephi e depois instale o novo .nbm.
Do pacote gephi-mcp: o servidor agora é publicado como gephi-ai. Se sua configuração disser uvx gephi-mcp, mude para uvx gephi-ai para continuar recebendo atualizações.
Do nome de servidor gephi-mcp: os comandos de configuração e o plugin do Claude agora nomeiam o servidor como gephi-ai, então suas ferramentas aparecem como mcp__gephi-ai__gephi_* (mcp__plugin_gephi-network-analysis_gephi-ai__gephi_* do plugin). Um servidor que você registrou manualmente como gephi-mcp continua funcionando com esse nome; registre-o novamente como gephi-ai para corresponder e aprove as ferramentas uma vez.
Cowork mantém sua própria cópia de plugins. Peça ao Cowork para atualizar o gephi-network-analysis e depois feche e reabra completamente o aplicativo.

Solução de problemas

"Executable not found in $PATH": o aplicativo não consegue encontrar uvx ou gephi-ai. Instale com uvx ou pipx em vez de dentro de um ambiente virtual do projeto, ou aponte sua configuração para o caminho completo do executável.
Toda ferramenta aparece duas vezes: dois métodos de conexão estão ativos. Remova um (pacote: Configurações > Extensões; arquivo de configuração: exclua o bloco gephi-ai, ou gephi-mcp em uma configuração mais antiga).
"Graph is busy" aparece repetidamente: feche e reabra completamente o Gephi.
Relatando um bug: anexe o log do Gephi (messages.log na pasta de usuário do Gephi, em var/log; no macOS ~/Library/Application Support/gephi/0.11/var/log/). A partir do plugin 1.5.2, uma solicitação que falha dentro do Gephi registra seu stack trace lá.
Abrir http://127.0.0.1:8080 em um navegador retorna 403: isso é intencional. A API recusa navegadores para que uma página da web não possa controlar o Gephi. curl http://127.0.0.1:8080/health mostra se o plugin está em execução.

Segurança

A API do plugin escuta em 127.0.0.1 apenas e recusa solicitações de navegadores e de nomes de host não locais. Ela não tem autenticação, então qualquer programa executado sob sua conta pode usá-la. Não exponha a porta 8080.

Ferramentas (120)

Categoria	Contagem	Exemplos
Projeto e Espaço de Trabalho	12	`gephi_create_project`, `gephi_save_project`, `gephi_duplicate_workspace`, `gephi_snapshot`, `gephi_undo`
Construção de Grafo	18	`gephi_add_nodes`, `gephi_add_edges`, `gephi_query_nodes`, `gephi_get_node`, `gephi_text_to_network`, `gephi_bipartite_projection` (dois modos para um modo)
Estatísticas e Análise	21	`gephi_compute_modularity`, `gephi_run_statistic` (qualquer métrica instalada), `gephi_compare_partitions` (grupos detectados contra grupos conhecidos), `gephi_find_shortest_path`, `gephi_whatif` (contrafactual), `gephi_compare_nodes`, `gephi_community_stability` (as comunidades são reais?), `gephi_compare_workspaces` (o que mudou entre duas versões)
Layout	9	`gephi_run_layout`, `gephi_get_layout_properties`, `gephi_community_layout`, `gephi_similarity_layout`, `gephi_bipartite_layout`
Aparência	11	`gephi_color_by_partition`, `gephi_color_edges_by_partition`, `gephi_size_by_ranking`, `gephi_label_clusters`
Filtragem	11	`gephi_filter_by_degree`, `gephi_extract_backbone`, `gephi_list_filters`, `gephi_apply_filter` (qualquer filtro, por nome), `gephi_apply_filters` (vários combinados)
Atributos	5	`gephi_get_columns`, `gephi_set_node_attributes`
Pré-visualização e Exportação	14	`gephi_export_png`, `gephi_export_screenshot` (captura ao vivo do canvas), `gephi_export_gexf`, `gephi_export` (VNA, Pajek, DL e mais), `gephi_view_graph`, `gephi_export_legend`, `gephi_export_figure` (mapa e legenda como um único PDF), `gephi_session_receipt` (como a figura foi feita)
Laboratório de Dados	5	`gephi_column_value_frequencies`, `gephi_detect_duplicates`, `gephi_merge_nodes`, `gephi_create_regex_column`, `gephi_edit_column`
Linha do Tempo	3	`gephi_get_timeline`, `gephi_set_time_from_columns` (tempo a partir de colunas de início e fim), `gephi_time_slice` (um período em seu próprio espaço de trabalho)
Importação	4	`gephi_import_file`, `gephi_import_gexf`
Saúde e Diagnóstico	3	`gephi_health_check`, `gephi_visual_qa`, `gephi_profile_graph`
Visualização / Câmera / Perspectiva	4	`gephi_focus_view`, `gephi_set_selection_mode`, `gephi_get_perspective`, `gephi_switch_perspective`

A referência completa, o guia de layout e o guia de estatísticas estão em plugins/claude-code/skills/gephi/.

Como funciona

AI assistant  →  MCP server (Python)  →  HTTP on 127.0.0.1:8080  →  Gephi plugin (Java)  →  Gephi Desktop

Componente	Diretório
Plugin do Gephi	`gephi-ai-plugin/`
Servidor MCP	`mcp-server/`
Plugin do Claude Code	`plugins/claude-code/`
Plugin do Codex	`plugins/gephi-network-analysis/`
Pacote do Claude Desktop	`mcpb/`

Desenvolvimento

O plugin do Gephi precisa de JDK 17 ou mais recente (as bibliotecas do Gephi 0.11.3 são Java 17) e Maven:

cd gephi-ai-plugin
mvn clean package    # builds target/gephi-ai-<version>.nbm and copies its jar into Gephi's modules folder

Feche e reabra completamente o Gephi após cada reconstrução. Substituir o plugin enquanto o Gephi está em execução pode travá-lo sem um erro claro. A compilação copia apenas o jar do módulo; quando as bibliotecas incluídas mudam, instale o .nbm completo (RELEASING.md, passo 3).

Cada compilação verifica o plugin antes de compilar e testá-lo:

Checkstyle é executado com a configuração do próprio núcleo do Gephi (gephi-ai-plugin/checkstyle.xml), e qualquer violação falha a compilação.
SourceRulesTest contém as regras que impedem o plugin de congelar o Gephi: locks de grafo liberados em finally, sem loops sobre iteradores de grafo ao vivo, sem alterações de projeto ou leituras de grafo na thread da interface, threads daemon nomeadas e o cabeçalho de licença em cada arquivo.

O servidor MCP é um pacote Python padrão em mcp-server/, testado com pytest, lintado com ruff e verificado de tipos com mypy. O CI falha quando a cobertura cai abaixo dos limites definidos em mcp-server/pyproject.toml e gephi-ai-plugin/pom.xml. Os scripts de release são verificados com shellcheck e testados em repositórios descartáveis, e o fluxo de trabalho do CI é verificado com actionlint. Em um pull request, o CI também executa scripts/check-fix-tests.sh, que avisa sobre um commit fix que não altera nenhum teste. O teste de fumaça ao vivo (mcp-server/tests/live_smoke_test.py) aciona todas as ferramentas contra um Gephi em execução; seu docstring fornece o comando para um Gephi de teste separado. As etapas de release estão em RELEASING.md.

Citação

Artz, Matt. 2025. Gephi AI. Software. Zenodo. https://doi.org/10.5281/zenodo.18673386

Se você adaptar este projeto, por favor credite "gephi-ai (Matt Artz, 2025–2026), https://github.com/MattArtzAnthro/gephi-ai".

Licença

Apache License 2.0. Veja LICENSE.

Autor

Matt Artz, mattartz.me | ORCID