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 lets AI agents read and edit your family
tree through the Model Context Protocol. It is not a genealogy UI: run it
alongside an existing Gramps Web instance, where your users, trees, media and
permissions stay.

The buttons add the server to VS Code or Cursor, which start it from the
Docker image, so Docker must be installed. For Claude Desktop, install the
MCPB extension; other clients are listed under
Install.
Features
- Up to 35 MCP tools β read, create, update, merge, and delete people,
families, events, places, sources, citations, notes, media, repositories,
and tags
- Search and kinship β full-text search, listings filtered by Gramps QL or
Gramps filter rules, ancestors, descendants, relationships, and timelines
- Careful edits β add or remove one link with
linkMode and keep the
rest; save a whole register entry in one transaction with create_records;
dates in every Gramps form and calendar
- Duplicates β
find_duplicates pairs people entered twice, across
spellings and name forms, and the create tools refuse a person the tree
already has
- Undo and confirmation β
undo_change reverts one transaction of the
edit history; it, delete_object and merge_objects ask the user, not
the model, before they change the tree, in clients that support MCP
elicitation
- Scans and photos β opt-in previews that vision-capable agents can read,
with EXIF/GPS metadata stripped, and uploads from a folder you choose
- 8 MCP resources and guided prompts β type vocabularies, tree metadata,
filter rules, and workflows for research, imports, citing facts, and
tree audits
- Read-only mode β publish only read tools and block direct mutation calls
- Any MCP client β stdio, Streamable HTTP, and legacy SSE, from a Claude
Desktop extension, a Docker image, or a single-file release binary
The tool catalog describes every tool,
resource and prompt. Upgrading from 1.x? Follow the
2.0 migration guide.
What to ask
Ask in your own words; the agent chooses the tools. The names stand for people
in your tree, and a Gramps ID such as I0012 works as well.
| You ask | You get |
|---|
| "Tell me about Maria GarcΓa." | Her names, events with dates and places, parents, spouses and children, citations and notes |
| "Who were Kenji Tanaka's great-grandparents?" | Each ancestor with a kinship label such as Father's mother, and birth and death dates and places |
| "How is Ivan Petrov related to Maria GarcΓa?" | The relationship in words, such as second cousin once removed, and the common ancestors by name |
| "Transcribe the baptism scan O0012." | The scan for the agent to read, and the transcription in its reply |
| "Add Thomas Weber, born 3 May 1881 in Hamburg, son of Karl and Anna Weber." | The new records with their Gramps IDs, people already in the tree reused, and what the text left open |
| "Enter entry 12 of the 1884 marriage register: the couple, their fathers and the witnesses." | The citation, the marriage, the new people and families saved in one transaction, which one undo_change takes back |
| "What changed today? Undo the last edit." | The edit history, then the earlier versions back, or a refusal naming the later edits the undo would overwrite |
Reading scans needs media access.
The tool catalog lists more
requests and the tools each one uses.
Install
You need a running Gramps Web instance and an account on it. Choose the setup
by client:
| Client | Setup |
|---|
| Claude Desktop | The MCPB extension, installed from one file; no Docker |
| VS Code, Cursor | The install buttons above; the client starts the Docker image |
| Claude Code, Codex, Gemini CLI, Antigravity CLI, Open WebUI and others | Connecting MCP clients: over HTTP to a shared server, or started by the client from the Docker image or the release binary |
| Several clients or machines | One server in Docker, Docker Compose or on Unraid, reached over HTTP |
Claude Desktop
- Download the
.mcpb bundle for your platform from the
latest release,
such as gramps-web-mcp-claude-desktop-osx-arm64-v*.mcpb for Apple Silicon.
- Double-click it, or drag it into the Claude Desktop window.
- Enter your Gramps Web URL, username, password/token, and tree UUID.
- Leave Read-only mode enabled for your first session; disable it only when you
want Claude to create or edit records.
- Complete installation and start a new chat.
Claude Desktop connects to servers added by URL from Anthropic's cloud, not
from your computer, so it cannot reach a server on your home network; use the
extension there. Installation
lists the bundle for each platform.
Docker
For one server that several clients share:
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
Clients then connect to http://<host>:8080/mcp with the API key, as shown
in Over HTTP. Add
-e GRAMPS_READ_ONLY=true for read-only mode.
Installation covers refresh tokens,
health checks, image verification, Docker Compose with Gramps Web, Unraid and
upgrades.
Configuration
Every setting is an environment variable. The main ones:
| Variable | Description | Default |
|---|
GRAMPS_API_URL | Base URL of your Gramps Web instance (no trailing slash) | β |
GRAMPS_USERNAME, GRAMPS_PASSWORD | The Gramps Web account the server works as | β |
GRAMPS_REFRESH_TOKEN | Used instead of the user name and password when Gramps Web has password login turned off | β |
GRAMPS_TREE_ID | Tree UUID on that server | β |
GRAMPS_READ_ONLY | true publishes only read tools and blocks writes | false (the Claude Desktop extension: true) |
GRAMPS_MEDIA_RESOURCES_ENABLED | Lets agents read scans and photos, and enables uploads | false |
GRAMPS_MEDIA_UPLOAD_DIRS | Folders that create_media may upload from | unset (off) |
MCP_TRANSPORT | stdio, http (Streamable HTTP) or sse | stdio (the Docker image: http) |
MCP_API_KEY | Key that HTTP clients must send; set it whenever other machines can reach the port | β |
Configuration describes every setting,
including write pacing for SQLite, confirmation dialogs, media limits,
transports, browser origins and logging.
Documentation
| Document | Description |
|---|
| Installation | Claude Desktop, Docker, Docker Compose, Unraid, health checks, and upgrades |
| Connecting MCP clients | Claude Code, VS Code, Cursor, Codex, Gemini and Antigravity CLI, and Open WebUI, over HTTP or stdio |
| Configuration | Every environment variable |
| Tool catalog | Every tool, resource and prompt, and more example requests |
| System prompt | Suggested prompt for MCP clients |
| Migrating to 2.0 | Tool replacements and setup changes for 1.x users |
| Claude Desktop MCPB | Desktop extension packaging |
| Architecture | System design overview |
| Developer guide | Running from source, tests, and adding tools |
| docs index | All documentation files |
Contributing
Contributions are welcome. ./run-local-server.sh runs the server from source
against the public demo.grampsweb.org tree at
http://127.0.0.1:8080/mcp, and dotnet test runs the tests. See
CONTRIBUTING.md and the
developer guide.
gramps-web-mcp is free and open source. If it helps your research, you can
support its development through
GitHub Sponsors, monthly or once.
Sponsors whose tier includes a mention are listed here.
Security
To report a vulnerability, see SECURITY.md.
Privacy Policy
The Claude Desktop extension is a local MCP server. It sends data only to the
Gramps Web instance you configure and does not collect analytics or conversation
data. See PRIVACY.md for full details.
License
Copyright (c) Scormave
This project is licensed under the GNU Affero General Public License v3.0
(AGPL-3.0-or-later). Because this is network server software, hosting a modified
version requires making the corresponding source available to users interacting
with it over a network.
Bundled third-party components, such as ImageSharp, the MCP C# SDK, and the .NET
runtime, keep their own Apache 2.0 or MIT licenses; see
THIRD-PARTY-NOTICES.txt. The MCP Bundles and the
Docker image ship that file next to LICENSE.