Gramps Web MCP server

gramps-web-mcp

Companion MCP server for the Gramps Web open-source genealogy platform. It gives AI agents structured, tool-based access to family trees through the Model Context Protocol.

This project is not a standalone genealogy UI or replacement for Gramps Web. Run it alongside an existing Gramps Web instance; your users, trees, media, permissions, and genealogy editing UI stay in Gramps Web.

Features

sources, citations, notes, media, repositories, and tags

• 57 MCP tools — read, create, update, and delete people, families, events, places,

settings, and opt-in media thumbnails/files for vision-capable agents

• Search and browse — full-text search and paginated object listing
• Kinship tools — ancestors, descendants, relationships, and timelines
• Composite workflows — quick-add person, add event to person, find by Gramps ID
• 6 MCP resources — type vocabularies, input guide, tree metadata, name

• Media safeguards — size limits, MIME allowlists, and private-record defaults
• MCP prompts — guided workflows for research, adding people/families, and imports
• Multiple transports — stdio (local clients), Streamable HTTP, legacy SSE
• Read-only mode — keep all tools visible while blocking create, update, and delete calls

See the tool catalog for the full list.

All outgoing requests to Gramps Web, including authentication, media downloads, and health checks, automatically identify this application with User-Agent: gramps-web-mcp/ (+https://github.com/Scormave/gramps-web-mcp). The version comes from the application build; no configuration is required.

Prerequisites

• .NET 10 SDK (for local development)
• A running Gramps Web instance with API access
• Docker (optional, for container deployment)

Quick start

Local development (demo server)

run-local-server.sh connects to the public demo.grampsweb.org instance using well-known demo credentials (owner / owner):

./run-local-server.sh

The server starts with HTTP transport at http://127.0.0.1:8080/mcp. No API key is required when binding to loopback only.

Docker

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry. Docker picks the matching architecture automatically; amd64 covers most Unraid and x86 hosts, arm64 covers Apple Silicon and ARM SBCs:

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

The image exposes a GET /health endpoint for Docker HEALTHCHECK, Unraid container health, and other uptime monitors. It returns HTTP 200 when the MCP server can authenticate against Gramps Web, or HTTP 503 otherwise. The public response is minimal by default: { "status": "healthy" } or { "status": "unhealthy" }. Startup logs include a line such as Connected to Gramps Web at … once the API is reachable.

The image defaults to Streamable HTTP (MCPTRANSPORT=http) on port 8080, which is what the commands above use. Clients that spawn the container themselves (such as MCP Registry installs) instead run it over stdio with -e MCPTRANSPORT=stdio and stdin kept open (docker run -i); that is the mode declared in server.json.

For read-only mode, add -e GRAMPSREADONLY=true:

Shortened. The full README is on GitHub.