gramps-web-mcp

Servidor MCP complementario para la plataforma de genealogía de código abierto Gramps Web. Proporciona a los agentes de IA acceso estructurado y basado en herramientas a árboles genealógicos a través del Model Context Protocol.

Este proyecto no es una interfaz de usuario de genealogía independiente ni un reemplazo de Gramps Web. Ejecútelo junto a una instancia existente de Gramps Web; sus usuarios, árboles, medios, permisos e interfaz de edición genealógica permanecen en Gramps Web.

Características

• 57 herramientas MCP — leer, crear, actualizar y eliminar personas, familias, eventos, lugares, fuentes, citas, notas, medios, repositorios y etiquetas

• Búsqueda y navegación — búsqueda de texto completo y listado paginado de objetos

• Herramientas de parentesco — antepasados, descendientes, relaciones y cronologías

• Flujos de trabajo compuestos — añadir persona rápidamente, añadir evento a persona, buscar por ID de Gramps

• 6 recursos MCP — vocabularios de tipos, guía de entrada, metadatos del árbol, configuraciones de nombres y miniaturas/archivos multimedia opcionales para agentes con capacidad de visión

• Salvaguardas multimedia — límites de tamaño, listas blancas MIME y valores predeterminados de registros privados

• Indicaciones MCP — flujos de trabajo guiados para investigación, adición de personas/familias e importaciones

• Múltiples transportes — stdio (clientes locales), HTTP Streamable, SSE heredado

• Modo de solo lectura — mantiene todas las herramientas visibles mientras bloquea las llamadas de creación, actualización y eliminación

Consulte el catálogo de herramientas para obtener la lista completa.

Related MCP server: ASPNET Core Debugging MCP Server

Requisitos previos

• .NET 8 SDK (para desarrollo local)

• Una instancia en ejecución de Gramps Web con acceso a la API

• Docker (opcional, para implementación en contenedor)

Inicio rápido

Desarrollo local (servidor de demostración)

run-local-server.sh se conecta a la instancia pública demo.grampsweb.org utilizando las credenciales de demostración conocidas (owner / owner):

./run-local-server.sh

El servidor se inicia con transporte HTTP en http://127.0.0.1:8080/mcp. No se requiere clave API al vincularse solo a loopback.

Docker

Las imágenes multiarquitectura preconstruidas (linux/amd64, linux/arm64) se publican en GitHub Container Registry. Docker selecciona la arquitectura coincidente automáticamente; amd64 cubre la mayoría de los hosts Unraid y x86, arm64 cubre Apple Silicon y SBC ARM:

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

La imagen expone un endpoint GET /health para HEALTHCHECK de Docker, estado del contenedor Unraid y otros monitores de tiempo de actividad. Devuelve HTTP 200 cuando el servidor MCP puede autenticarse contra Gramps Web, o HTTP 503 en caso contrario. La respuesta pública es mínima por defecto: { "status": "healthy" } o { "status": "unhealthy" }. Los registros de inicio incluyen una línea como Connected to Gramps Web at … una vez que la API es accesible.

La imagen utiliza por defecto HTTP Streamable (MCP_TRANSPORT=http) en el puerto 8080, que es lo que utilizan los comandos anteriores. Los clientes que inician el contenedor ellos mismos (como las instalaciones de MCP Registry) lo ejecutan a través de stdio con -e MCP_TRANSPORT=stdio y stdin abierto (docker run -i); ese es el modo declarado en server.json.

Para el modo de solo lectura, añada -e GRAMPS_READ_ONLY=true:

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Instalación en Unraid

Los usuarios de Unraid pueden instalar gramps-web-mcp desde Community Applications. La fuente de la plantilla se mantiene en Scormave/gramps-web-mcp-unraid. Para obtener ayuda específica de Unraid, consulte el hilo de soporte en los foros de Unraid.

Configuración básica:

1. En Unraid, abra Apps / Community Applications.

2. Busque gramps-web-mcp e instale la plantilla.

3. Establezca GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD y GRAMPS_TREE_ID para su instancia de Gramps Web. Establezca MCP_API_KEY cuando el puerto MCP sea accesible desde otras máquinas de su red.

4. Mantenga el puerto de contenedor predeterminado 8080, o asígnelo a otro puerto del host.

5. Inicie el contenedor y verifique /health; devuelve HTTP 200 una vez que el servicio puede autenticarse en Gramps Web, con una respuesta JSON mínima por defecto.

Para el emparejamiento más sencillo, ejecute Gramps Web y gramps-web-mcp en la misma red Docker de Unraid y establezca GRAMPS_API_URL en la URL del contenedor de Gramps Web. El endpoint MCP para los clientes es http://<unraid-host>:<mapped-port>/mcp.

Gramps Web + MCP (Docker Compose)

Para ejecutar Gramps Web y el servidor MCP en el mismo host y red Docker, utilice docker-compose.example.yml como punto de partida:

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web se publica en el puerto 5055; MCP está en el 8080 (/mcp y /health). Dentro de la red de compose, el contenedor MCP accede a Gramps Web en http://grampsweb:5000.

Claude Desktop (extensión MCPB)

La instalación con un solo clic para Claude Desktop está disponible como un MCP Bundle (.mcpb) desde GitHub Releases. Descargue el paquete para su plataforma:

1. Descargue el archivo .mcpb para su sistema operativo desde la última versión.

2. Haga doble clic en él, o arrástrelo a la ventana de Claude Desktop.

3. Introduzca su URL de Gramps Web, nombre de usuario, contraseña/token y UUID del árbol.

4. Deje el Modo de solo lectura habilitado para su primera sesión; desactívelo solo cuando desee que Claude cree o edite registros.

5. Complete la instalación e inicie un nuevo chat.

La extensión se ejecuta localmente a través de stdio y no requiere el SDK de .NET en su máquina. Consulte mcpb/README.md para obtener detalles sobre el empaquetado y PRIVACY.md para la política de privacidad.

Para construir un paquete localmente:

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

Configuración del cliente MCP (manual)

stdio (ej. Claude Desktop, Cursor):

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

Para ejecutar un servidor stdio en modo de solo lectura, añada "GRAMPS_READ_ONLY": "true" a env.

HTTP (remoto / Docker):

Apunte su cliente MCP a http://host:8080/mcp con transporte HTTP Streamable. Cuando MCP_API_KEY esté configurada, envíela como Authorization: Bearer <key> o X-Api-Key: <key> en cada solicitud MCP.

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

Los agentes con capacidad de visión pueden leer medios opcionales a través de herramientas (GetMediaThumbnail, GetMediaFile) o a través de recursos MCP binarios como gramps://media/{handle}/thumbnail/{size} y gramps://media/{handle}/file. GetMediaFile devuelve contenido de recurso de imagen, audio o blob incrustado según el tipo MIME. El análisis de extremo a extremo depende de que el cliente MCP reenvíe el contenido de la herramienta tipificada o el contenido del recurso binario a un modelo capaz.

Configuración

Requerido (conexión a Gramps)

Modo de ejecución

• GRAMPS_READ_ONLY: establézcalo en true para bloquear las llamadas de creación, actualización y eliminación mientras mantiene las herramientas visibles.

• GRAMPS_MUTATION_SERIALIZE: ejecuta las llamadas HTTP de creación/actualización/eliminación una a la vez en este proceso.

• GRAMPS_MUTATION_MIN_INTERVAL_MS: pausa mínima entre llamadas HTTP de mutación, incluidos los pasos dentro de las herramientas compuestas.

Notas de ejecución:

• GRAMPS_READ_ONLY=false significa que el servidor se inicia en modo lectura/escritura.

• La extensión MCPB de Claude Desktop es la excepción: su formulario de configuración predetermina el modo de solo lectura para un primer uso más seguro.

• La serialización de escritura y el intervalo opcional protegen los árboles SQLite típicos de Gramps Web de las ráfagas de escritura del agente.

• La puerta de escritura es solo dentro del proceso. No se coordina entre múltiples réplicas MCP, la interfaz de usuario de Gramps Web u otros clientes API.

• Las implementaciones SQLite que aún ven database is locked en ediciones secuenciales deben establecer GRAMPS_MUTATION_MIN_INTERVAL_MS=250 o 500.

• En errores de bloqueo de SQLite o HTTP 429 ascendente, las herramientas de mutación devuelven un error MCP reintentable con una sugerencia de retroceso corta en lugar de un 500 genérico.

• Establezca GRAMPS_MUTATION_SERIALIZE=false cuando Gramps Web utilice PostgreSQL y desee escrituras paralelas.

Acceso a archivos multimedia

Las herramientas/recursos de bytes multimedia están deshabilitados por defecto. get_media permanece disponible para metadatos sin habilitar descargas de archivos.

Prefiera GetMediaThumbnail o gramps://media/{handle}/thumbnail/{size} para el análisis de IA. Los archivos completos pueden ser grandes y sensibles, y aún están sujetos a las mismas comprobaciones de tamaño, MIME y registros privados.

Se admiten tipos exactos y comodines type/*. La lista blanca de medios predeterminada es image/jpeg,image/png,image/webp,image/avif,application/pdf.

Transportes

Establezca GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD y GRAMPS_TREE_ID como de costumbre.

Para transporte HTTP, las respuestas se transmiten a través de SSE. Consulte la especificación de HTTP Streamable para obtener detalles del protocolo. Establezca ASPNETCORE_URLS para elegir la dirección de escucha, por ejemplo http://127.0.0.1:8080.

Opcional (transporte MCP)

Autenticación HTTP

Cuando MCP_API_KEY está definida, todos los endpoints HTTP/SSE de MCP requieren la clave en cada solicitud. GET /health permanece anónimo para las sondas de Docker y del balanceador de carga.

Genera una clave:

openssl rand -base64 32

Sin una clave, el servidor sigue iniciándose (compatible con versiones anteriores). Si la dirección de escucha no es solo de loopback, se registra una advertencia que te recomienda establecer MCP_API_KEY, usar un proxy inverso con su propia autenticación o enlazar a 127.0.0.1 para uso únicamente local.

Dentro de Docker, ASPNETCORE_URLS suele ser http://0.0.0.0:8080, por lo que la advertencia aparece incluso cuando el host publica el puerto únicamente en 127.0.0.1. Esto es lo esperado cuando el acceso externo ya está restringido.

Desarrollo

dotnet test

Consulta CONTRIBUTING.md y la guía para desarrolladores.

Documentación

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md.

Seguridad

Para notificar una vulnerabilidad, consulta SECURITY.md.

Política de privacidad

La extensión de Claude Desktop es un servidor MCP local. Solo envía datos a la instancia de Gramps Web que configures y no recopila datos de análisis ni de conversación. Consulta PRIVACY.md para conocer todos los detalles.

Licencia

Copyright (c) Scormave

Este proyecto está licenciado bajo la GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Al tratarse de software de servidor de red, alojar una versión modificada requiere poner el código fuente correspondiente a disposición de los usuarios que interactúan con ella a través de una red.