Scormave/gramps-web-mcp

> [!WARNING]
> **Update to 2.3.1 or later.** Before 2.3.1 the update_* tools could drop
> stored data that the call did not mention
> (#5). If you edited a
> tree with an earlier version,
> check it for dropped data.
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
- **Up to 30 MCP tools** — read, create, update, and delete people, families, events, places,
sources, citations, notes, media, repositories, and tags
- **Search and browse** — full-text search and paginated object listing,
filtered by Gramps QL or by Gramps filter rules (everyone related to a
person, people with no family links)
- **Kinship tools** — ancestors, descendants, relationships, and timelines
- **Incremental links** — add or remove one event, child, citation, or note
with linkMode, keeping every other link
- **Dates as Gramps writes them** — ranges, before/after/about, and every Gramps
calendar (1856-07-20 (Julian)), stored with the sort value Gramps computes
- **8 MCP resources** — type vocabularies, input guide, tree metadata, name
settings, filter rules, and opt-in media previews/files for vision-capable
agents
- **Media safeguards** — size limits, private-record defaults, and previews with
EXIF/GPS metadata stripped
- **MCP prompts** — guided workflows for research, finding connections, adding
people/families, imports, changing links, and citing facts
- **Multiple transports** — stdio (local clients), Streamable HTTP, legacy SSE
- **Read-only mode** — publish only read tools and block direct mutation calls
See the tool catalog for the full list.
Upgrading from 1.x? Follow the 2.0 migration guide
to update saved tool calls and client settings.
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):
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:
For refresh-token authentication, replace the GRAMPS_USERNAME and
GRAMPS_PASSWORD lines with -e GRAMPS_REFRESH_TOKEN=your-refresh-token.
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. Probes reuse
the token the tools use, so they do not log in to Gramps Web each time. The
public response is minimal: { "status": "healthy" } or
{ "status": "unhealthy" }. Startup logs include a line such as
Connected to Gramps Web at … once the API is reachable.
The image is built on Ubuntu Chiseled and has no shell or curl. Its
HEALTHCHECK runs dotnet /app/GrampsWeb.Mcp.dll --health-check, which
requests /health on the port from ASPNETCORE_URLS and exits with 0 on
HTTP 200 and 1 otherwise. A health check you define yourself, in Compose or in
a NAS app template, runs the same command:
If the server listens on an address that ASPNETCORE_URLS does not give, pass
the URL after the option, for example --health-check http://localhost:9000.
The image defaults to Streamable HTTP (MCP_TRANSPORT=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 MCP_TRANSPORT=stdio and stdin kept open (docker run -i); that is the mode