gramps-mcp

An unofficial MCP server that exposes one or more Gramps Web API trees to LLM assistants (Claude, etc.), against your own genealogy data.

Since several assistants (e.g. Claude, Antigravity) support voice input, this works particularly well hands-free and conversationally: you can ask an open-ended research question — "give me a breakdown of the social classes of the people in this tree" — or edit the tree live by voice, the same way you'd dictate a change to an assistant in any other MCP-backed app.

It works by pointing FastMCP's FastMCP.from_openapi() at your Gramps Web API instance's openapi.json and auto-generating one MCP tool per REST endpoint, mounting one sub-server per configured tree behind optional Google OAuth and a per-tree membership check.

Status and scope

This is a community project, not affiliated with or endorsed by the Gramps project. See gramps-web-api#1003 for the maintainer's position: Gramps Web API intentionally exposes an open, scriptable REST API, but the project won't officially endorse an MCP layer on top of it, in part because the Gramps database model is not very fault tolerant — a bad write (dangling reference, wrong schema, etc.) can corrupt a tree, and that risk is higher when requests are agent-generated rather than hand-written. Point this at a tree you're prepared to back up and, if necessary, recover from an LLM's mistakes. It's aimed at users comfortable with that trade-off, not a general recommendation.

gramps-web-api#943 and its follow-ups (#944, #971) improved openapi.json specifically to make this kind of generation work cleanly — every operation now has a unique operationId and a specific summary, and mutation endpoints document their request body.

Related MCP server: gramps-ez-mcp

Configure

Copy .env.example to .env and fill in, at minimum:

• GRAMPS_BACKEND_URL — your Gramps Web API instance's base URL.

• GRAMPS_MCP_TREES — comma-separated tree names to mount.

• GRAMPS_MCP_TREE_<NAME>_USERNAME / _PASSWORD — a Gramps Web user's credentials for each tree in GRAMPS_MCP_TREES (<NAME> is the tree name uppercased, non-alphanumeric characters replaced by _).

Everything else in .env.example is optional. In particular, GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET gate the server behind Google sign-in and a Redis-backed per-tree membership check (GRAMPS_MCP_ADMIN_EMAILS plus each tree's own Gramps Web user list) — leave them unset only for a server you run purely on localhost for yourself.

By default, /api/filters/, /api/token/, /api/users/, /api/facts/, and config endpoints are excluded from the generated tool set — see EXCLUDED_ROUTE_PREFIXES in src/gramps_mcp/trees.py.

Docker Compose example

This assumes you already have a Gramps Web API instance running (e.g. from its own docker-compose.yml). docker-compose.yml here is meant as an addition to that base stack, not a replacement for it — it only adds the gramps-mcp and redis services shown below, joined to the same Docker network as the existing grampsweb service(s) so GRAMPS_BACKEND_URL can reach it. If that base stack already runs its own Redis (Gramps Web API uses one for Celery and rate-limiting), you can point MCP_CLIENT_STORAGE_URL at it on an unused DB index instead of adding a second redis service.

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

  gramps-mcp:
    build: .
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      GRAMPS_BACKEND_URL: "${GRAMPS_BACKEND_URL}"
      GRAMPS_MCP_TREES: "${GRAMPS_MCP_TREES}"
      GRAMPS_MCP_TREE_MYTREE_USERNAME: "${GRAMPS_MCP_TREE_MYTREE_USERNAME}"
      GRAMPS_MCP_TREE_MYTREE_PASSWORD: "${GRAMPS_MCP_TREE_MYTREE_PASSWORD}"
      GRAMPS_MCP_ADMIN_EMAILS: "${GRAMPS_MCP_ADMIN_EMAILS:-}"
      GOOGLE_CLIENT_ID: "${GOOGLE_CLIENT_ID:-}"
      GOOGLE_CLIENT_SECRET: "${GOOGLE_CLIENT_SECRET:-}"
      MCP_BASE_URL: "${MCP_BASE_URL:-https://mcp.example.com}"
      MCP_GOOGLE_REDIRECT_PATH: "${MCP_GOOGLE_REDIRECT_PATH:-/auth/callback}"
      # Redis backs the OAuth client store, so registered MCP clients and
      # their tokens survive a container restart instead of forcing every
      # client to re-authorize.
      MCP_CLIENT_STORAGE_URL: "redis://redis:6379/0"
      MCP_HOST: "0.0.0.0"
      MCP_PORT: "8000"
    depends_on:
      - redis

volumes:
  redis_data:

Run it with docker compose up -d after populating a .env (see Configure) with at least GRAMPS_BACKEND_URL, GRAMPS_MCP_TREES, and the matching GRAMPS_MCP_TREE_<NAME>_USERNAME/_PASSWORD pair(s). Google OAuth (and therefore Redis) is only exercised once GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET are set; without them the server still runs, unauthenticated, for local/single-user use. Point your MCP client at http://<host>:8000/mcp.

GQL resource

The server also publishes a gramps://gql-spec MCP resource with the Gramps Query Language reference, so an agent can look up GQL syntax before constructing a gql= filter against a tree's search tools.

License

MIT.