Gephi MCP

Controla Gephi Desktop desde tu asistente de IA con 80 herramientas para construir, analizar, diseñar y estilizar grafos de redes, además de un visor interactivo de grafos dentro del chat.

GitHub

Documentación

Gephi AI

Controla Gephi hablando con tu asistente de IA. Construye, analiza, estiliza y exporta mapas de redes listos para publicación a través del Protocolo de Contexto de Modelo (MCP).

Diseñado para investigadores que trabajan en ciencia de redes e IA.

Estado: beta pública. Las APIs pueden cambiar entre versiones menores.

Lo que obtienes

Tu asistente de IA maneja Gephi. Di lo que quieras en lenguaje natural y el asistente construye, analiza, estiliza y exporta el mapa.

Es una conversación, no una línea de comandos. El asistente explica lo que está haciendo, revisa sus propios mapas antes de mostrarlos y te enseña a leer lo que ves. Puedes señalar hacia atrás: selecciona nodos en Gephi y pregunta "¿qué seleccioné?"

Cualquier dato, cualquier cliente MCP. Los archivos de red se importan directamente, y las hojas de cálculo y otros datos se convierten en redes conversacionalmente. Funciona con Claude Code, Claude Desktop, OpenAI Codex, Gemini CLI o cualquier cliente MCP.

Lista completa de funciones

120 herramientas que cubren todo el flujo de trabajo: construir, analizar, estilizar, distribuir, filtrar y exportar
Deshacer de un nivel: las operaciones destructivas crean una instantánea del espacio de trabajo primero, así que gephi_undo devuelve el grafo
Calidad de distribución medida: el perfil del grafo señala pesos de cola pesada y cableado hub-and-spoke antes de que se ejecute una distribución, la revisión visual puntúa qué tan bien se separan las comunidades, y las distribuciones numéricamente explotadas se detectan en lugar de exportarse
Vista de red interactiva dentro del chat (pan, zoom, pasar el cursor y hacer clic en un nodo para preguntar sobre él)
Comandos de barra para tareas comunes: /analyze-network, /community-detection, /centrality, /visualize, /export-map, /import-and-explore, /explore, /verify-claim, /text-network, /teach y /counterfactual
Agentes especializados para verificación de afirmaciones, iteración de distribución, análisis estructural y redes de texto
Dos distribuciones adicionales más allá de las de Gephi: por rol en la red y por comunidad
Lee tu selección en la ventana de Gephi
Maneja cualquier distribución o plugin de métricas instalado desde el portal de plugins de Gephi
Importa GEXF, GraphML, GML, CSV, DOT y Pajek

Instalación

Necesitas Gephi Desktop 0.11.3 o más reciente y un asistente de IA. La mayoría de los clientes también necesitan uv, que ejecuta el servidor y gestiona Python por ti; Claude Desktop trae el suyo propio.

1. Añade el plugin a Gephi

Descarga gephi-ai-1.5.2.nbm desde la página de Releases.
En Gephi, abre Herramientas > Plugins > Descargados > Añadir Plugins, selecciona el archivo y haz clic en Instalar.
Reinicia Gephi. Herramientas > Servidor Gephi AI muestra que el plugin está en ejecución.

2. Conecta tu asistente

Usa un método de conexión por aplicación. Dos a la vez significa dos servidores y cada herramienta listada dos veces.

Claude Code (recomendado: añade los comandos de barra, agentes y habilidades):

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

Claude Desktop: descarga gephi-ai-<version>.mcpb desde la página de Releases y haz doble clic en él. Claude Desktop instala Python, el servidor y sus dependencias por sí mismo. El primer lanzamiento necesita conexión a internet y puede tardar un minuto. Probado con Claude Desktop 1.40609.0.

OpenAI Codex (añade los mismos flujos de trabajo como habilidades):

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

Inicia una nueva tarea de Codex después de instalar.

Gemini CLI:

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

Cualquier otro cliente MCP: ejecuta uvx gephi-ai sobre stdio.

Solo herramientas, sin las habilidades y comandos

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

Claude Desktop a través de su archivo de configuración (claude_desktop_config.json):

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

Guía de análisis de redes para otros agentes

Copia la carpeta de habilidades al directorio de habilidades de tu agente:

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

Agente	Directorio de habilidades
OpenAI Codex	`~/.codex/skills/` (o instala el plugin de Codex anterior)
Cursor	`~/.cursor/skills/`
GitHub Copilot / VS Code	`~/.copilot/skills/`
Cualquier agente, por proyecto	`.agents/skills/` en tu repositorio

El repositorio también incluye AGENTS.md y GEMINI.md, que esos agentes leen por sí mismos.

3. Comprueba que funciona

Con Gephi abierto, pregunta a tu asistente: "Comprueba si Gephi está en ejecución." Debería llamar a gephi_health_check y confirmar la conexión, incluyendo si tu plugin y servidor están actualizados.

Actualización

La comprobación de salud te avisa una vez por sesión cuando algo está desactualizado.

Claude Code: claude plugin update gephi-network-analysis@gephi-ai, luego inicia una nueva sesión.
Paquete de Claude Desktop: descarga el .mcpb más reciente desde Releases y haz doble clic en él.
Archivo de configuración o configuraciones de uvx: no hay nada que hacer; uvx obtiene la última versión cuando la aplicación se reinicia.
Plugin de Gephi: instala el .nbm más reciente a través de Herramientas > Plugins > Descargados y reinicia Gephi.

Notas de actualización

Desde el plugin 1.2.x (una vez): el plugin se renombró a Gephi AI, así que la nueva versión se instala junto a la antigua y ambas intentan usar el puerto 8080. En Herramientas > Plugins > Instalados, desinstala Gephi AI (MCP), reinicia Gephi y luego instala el nuevo .nbm.
Desde el paquete gephi-mcp: el servidor ahora se publica como gephi-ai. Si tu configuración dice uvx gephi-mcp, cámbialo a uvx gephi-ai para seguir recibiendo actualizaciones.
Desde el nombre de servidor gephi-mcp: los comandos de configuración y el plugin de Claude ahora nombran el servidor gephi-ai, así que sus herramientas se muestran como mcp__gephi-ai__gephi_* (mcp__plugin_gephi-network-analysis_gephi-ai__gephi_* desde el plugin). Un servidor que registraste manualmente como gephi-mcp sigue funcionando bajo ese nombre; vuelve a registrarlo como gephi-ai para que coincida, y vuelve a aprobar las herramientas una vez.
Cowork mantiene su propia copia de los plugins. Pide a Cowork que actualice gephi-network-analysis, luego cierra y vuelve a abrir la aplicación por completo.

Solución de problemas

"Ejecutable no encontrado en $PATH": la aplicación no puede encontrar uvx o gephi-ai. Instala con uvx o pipx en lugar de dentro de un entorno virtual de proyecto, o apunta tu configuración a la ruta completa del ejecutable.
Cada herramienta aparece dos veces: hay dos métodos de conexión activos. Elimina uno (paquete: Configuración > Extensiones; archivo de configuración: elimina el bloque gephi-ai, o gephi-mcp en una configuración más antigua).
"El grafo está ocupado" aparece repetidamente: cierra y vuelve a abrir Gephi por completo.
Informar de un error: adjunta el registro de Gephi (messages.log en la carpeta de usuario de Gephi, bajo var/log; en macOS ~/Library/Application Support/gephi/0.11/var/log/). Desde el plugin 1.5.2, una solicitud que falla dentro de Gephi registra su traza de pila allí.
Abrir http://127.0.0.1:8080 en un navegador devuelve 403: esto es intencional. La API rechaza navegadores para que una página web no pueda manejar Gephi. curl http://127.0.0.1:8080/health muestra si el plugin está en ejecución.

Seguridad

La API del plugin escucha en 127.0.0.1 solamente y rechaza solicitudes de navegadores y de nombres de host no locales. No tiene autenticación, así que cualquier programa que se ejecute bajo tu cuenta puede usarla. No expongas el puerto 8080.

Herramientas (120)

Categoría	Recuento	Ejemplos
Proyecto y Espacio de Trabajo	12	`gephi_create_project`, `gephi_save_project`, `gephi_duplicate_workspace`, `gephi_snapshot`, `gephi_undo`
Construcción de Grafos	18	`gephi_add_nodes`, `gephi_add_edges`, `gephi_query_nodes`, `gephi_get_node`, `gephi_text_to_network`, `gephi_bipartite_projection` (de dos modos a un modo)
Estadísticas y Análisis	21	`gephi_compute_modularity`, `gephi_run_statistic` (cualquier métrica instalada), `gephi_compare_partitions` (grupos detectados frente a conocidos), `gephi_find_shortest_path`, `gephi_whatif` (contrafactual), `gephi_compare_nodes`, `gephi_community_stability` (¿son reales las comunidades?), `gephi_compare_workspaces` (qué cambió entre dos versiones)
Distribución	9	`gephi_run_layout`, `gephi_get_layout_properties`, `gephi_community_layout`, `gephi_similarity_layout`, `gephi_bipartite_layout`
Apariencia	11	`gephi_color_by_partition`, `gephi_color_edges_by_partition`, `gephi_size_by_ranking`, `gephi_label_clusters`
Filtrado	11	`gephi_filter_by_degree`, `gephi_extract_backbone`, `gephi_list_filters`, `gephi_apply_filter` (cualquier filtro, por nombre), `gephi_apply_filters` (varios combinados)
Atributos	5	`gephi_get_columns`, `gephi_set_node_attributes`
Vista Previa y Exportación	14	`gephi_export_png`, `gephi_export_screenshot` (captura de lienzo en vivo), `gephi_export_gexf`, `gephi_export` (VNA, Pajek, DL y más), `gephi_view_graph`, `gephi_export_legend`, `gephi_export_figure` (mapa y leyenda como un solo PDF), `gephi_session_receipt` (cómo se hizo la figura)
Laboratorio de Datos	5	`gephi_column_value_frequencies`, `gephi_detect_duplicates`, `gephi_merge_nodes`, `gephi_create_regex_column`, `gephi_edit_column`
Línea de Tiempo	3	`gephi_get_timeline`, `gephi_set_time_from_columns` (tiempo desde columnas de inicio y fin), `gephi_time_slice` (un período en su propio espacio de trabajo)
Importación	4	`gephi_import_file`, `gephi_import_gexf`
Salud y Diagnóstico	3	`gephi_health_check`, `gephi_visual_qa`, `gephi_profile_graph`
Vista / Cámara / Perspectiva	4	`gephi_focus_view`, `gephi_set_selection_mode`, `gephi_get_perspective`, `gephi_switch_perspective`

La referencia completa, la guía de distribución y la guía de estadísticas viven en plugins/claude-code/skills/gephi/.

Cómo funciona

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

Componente	Directorio
Plugin de Gephi	`gephi-ai-plugin/`
Servidor MCP	`mcp-server/`
Plugin de Claude Code	`plugins/claude-code/`
Plugin de Codex	`plugins/gephi-network-analysis/`
Paquete de Claude Desktop	`mcpb/`

Desarrollo

El plugin de Gephi necesita JDK 17 o más reciente (las bibliotecas de Gephi 0.11.3 son Java 17) y Maven:

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

Cierra y vuelve a abrir Gephi por completo después de cada reconstrucción. Reemplazar el plugin mientras Gephi está en ejecución puede bloquearlo sin un error claro. La compilación copia solo el jar del módulo; cuando las bibliotecas incluidas cambian, instala todo el .nbm (RELEASING.md, paso 3).

Cada compilación verifica el plugin antes de compilarlo y lo prueba:

Checkstyle se ejecuta con la propia configuración del núcleo de Gephi (gephi-ai-plugin/checkstyle.xml), y cualquier violación hace fallar la compilación.
SourceRulesTest contiene las reglas que evitan que el plugin congele Gephi: bloqueos de grafo liberados en finally, sin bucles sobre iteradores de grafo en vivo, sin cambios de proyecto o lecturas de grafo en el hilo de interfaz, hilos daemon nombrados y el encabezado de licencia en cada archivo.

El servidor MCP es un paquete estándar de Python en mcp-server/, probado con pytest, verificado con ruff y comprobado de tipos con mypy. CI falla cuando la cobertura baja de los mínimos establecidos en mcp-server/pyproject.toml y gephi-ai-plugin/pom.xml. Los scripts de lanzamiento se verifican con shellcheck y se prueban en repositorios desechables, y el flujo de trabajo de CI se verifica con actionlint. En una solicitud de extracción, CI también ejecuta scripts/check-fix-tests.sh, que advierte sobre un commit de fix que no cambia ninguna prueba. La prueba de humo en vivo (mcp-server/tests/live_smoke_test.py) maneja cada herramienta contra un Gephi en ejecución; su docstring da el comando para un Gephi de prueba separado. Los pasos de lanzamiento están en RELEASING.md.

Cita

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

Si adaptas este proyecto, por favor acredita "gephi-ai (Matt Artz, 2025–2026), https://github.com/MattArtzAnthro/gephi-ai".

Licencia

Licencia Apache 2.0. Ver LICENSE.

Autor

Matt Artz, mattartz.me | ORCID