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.
Built on FastMCP, it exposes a curated set of eight
tools—seven read operations and a single safe write tool, apply_changes—shared
across all configured trees behind optional Google OAuth and a per-tree membership
check. Rather than exposing dozens of raw REST endpoints that clutter the LLM's
context window, it unifies tree operations behind clean abstractions, presenting
every planned mutation to the user for interactive review and writing only once
confirmed.
Writing to a genealogy database requires strict care: invalid references or wrong schemas can corrupt a tree. gramps-mcp channels all modifications through a single entry point, apply_changes. When connected to an MCP client supporting MCP Apps (Prefab UI) (e.g. Visual Studio Code with Copilot), it turns planned changes into a live, interactive review card:
🔗 Try the live interactive card • 🎬 Watch the end-to-end demo video
- Visual status badges: Additions in green, edits in orange, and deletions in red.
- Automatic dependency cascades: Unticking a change automatically unticks everything that depends on it (e.g. unticking a person unticks their marriage family).
- Inline text editing: Fix names, descriptions, or surnames directly in the card before applying.
- Atomic rollback: If any change fails, all preceding changes in the transaction are rolled back atomically.
In clients without MCP Apps support, it seamlessly falls back to standard MCP text elicitation.
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.
The full documentation is at https://jerive.github.io/gramps-mcp/:
- Tutorial: run everything locally against Gramps' example tree, in about 15 minutes.
- How-to guides: service account, Google sign-in, Docker Compose, running without Docker, connecting an MCP client.
- Reference: every environment variable, and the generated tools.
- Explanation: how it works, and the security and risk model.
You need a running Gramps Web API instance with a tree, a Gramps Web user for that tree, and Python 3.12+.
# Tracks master. For reproducibility, pin a release by appending @<tag>, for
# example @v0.5.1; the tags are listed on the Releases page.
pip install "gramps-mcp @ git+https://github.com/jerive/gramps-mcp"
export GRAMPS_BACKEND_URL=http://localhost:5000
export GRAMPS_MCP_TREES=MyTree
export GRAMPS_MCP_TREE_MYTREE_USERNAME=myuser
export GRAMPS_MCP_TREE_MYTREE_PASSWORD=mypassword
export MCP_HOST=127.0.0.1 # without auth, only listen on localhost
gramps-mcpThen point your MCP client at http://localhost:8000/mcp. Prefer a Member
(read-only) Gramps user unless you want the agent to edit the tree.
MIT.