gramps-web-mcp
Docker app from Scormave's Repository
MCP server for Gramps Web — structured AI agent access to your family tree over HTTP.
Requirements
Overview
Readme
View on GitHubgramps-web-mcp
License: AGPL v3
.NET 10
MCP server version
Docker on GHCR
Gramps Web MCP MCP server – quality and maintenance score on Glama
Sponsor on GitHub
[!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.
Install in VS Code Install in VS Code Insiders Add to Cursor
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 field values or Gramps filter rules, ancestors, descendants, relationships, and timelines
- Careful edits — add or remove one link with
linkModeand keep the rest; save a whole register entry in one transaction withcreate_records; dates in every Gramps form and calendar - Duplicates —
find_duplicatespairs people entered twice, across spellings and name forms, and the create tools refuse a person the tree already has - History and undo —
get_recent_changesshows the edit history, or who changed each field of one record and what it held before;undo_changereverts one transaction. It,delete_objectandmerge_objectsask 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
.mcpbbundle for your platform from the latest release, such asgramps-web-mcp-claude-desktop-osx-arm64-v*.mcpbfor 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) |
GRAMPS_MEDIA_UPLOAD_HOSTS |
Hosts that files attached in the chat (ChatGPT) may be downloaded from; experimental | 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.
Sponsors
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.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/scormave/gramps-web-mcp:2.11.2Runtime arguments
- Network
bridge- Privileged
- false
Template configuration
Base URL of your Gramps Web instance (no trailing slash).
- Target
- GRAMPS_API_URL
- Value
- https://gramps.example.com
Gramps Web API username; use with Gramps Password, or leave blank when using a refresh token.
- Target
- GRAMPS_USERNAME
Gramps Web API password; use with Gramps Username, or leave blank when using a refresh token.
- Target
- GRAMPS_PASSWORD
Alternative to username and password, including when local password authentication is disabled. Takes precedence if both methods are set.
- Target
- GRAMPS_REFRESH_TOKEN
Tree UUID on the Gramps Web server.
- Target
- GRAMPS_TREE_ID
Set to true to publish only read tools and block direct create, update, and delete calls.
- Target
- GRAMPS_READ_ONLY
- Default
- false
- Value
- false
For delete_object, merge_objects and undo_change: when-supported asks capable clients; required refuses calls without a confirmation dialog; off skips it. HTTP dialogs also need MCP Stateless=false.
- Target
- GRAMPS_CONFIRMATION
- Default
- when-supported
- Value
- when-supported
Set false to omit anthropic/requiresUserInteraction metadata from delete_object, merge_objects and undo_change; client permission settings then decide. Does not disable server confirmation dialogs.
- Target
- GRAMPS_REQUIRE_USER_INTERACTION
- Default
- true
- Value
- true
Optional HTTP/SSE API key (Bearer or X-Api-Key), at least 16 characters. Comma-separated keys allow rotation. Recommended when the MCP port is reachable from other machines.
- Target
- MCP_API_KEY
Comma-separated trusted browser origins for HTTP/SSE, such as https://app.example.com (no path). Blank rejects requests with an Origin header; non-browser clients need no setting.
- Target
- MCP_ALLOWED_ORIGINS
Streamable HTTP defaults to stateless. Set false to allow confirmation dialogs in clients that support MCP elicitation; sessions then stay open.
- Target
- MCP_STATELESS
- Default
- true
- Value
- true
Serialize create, update, and delete HTTP calls in-process to reduce SQLite lock errors.
- Target
- GRAMPS_MUTATION_SERIALIZE
- Default
- true
- Value
- true
Optional minimum milliseconds between mutation HTTP calls (0 disables pacing).
- Target
- GRAMPS_MUTATION_MIN_INTERVAL_MS
- Default
- 0
- Value
- 0
Enable read_media, binary media resources, and uploads via create_media or update_media filePath.
- Target
- GRAMPS_MEDIA_RESOURCES_ENABLED
- Default
- false
- Value
- false
Maximum bytes returned by a media file or rendered preview; thumbnail generation can read originals up to 50 MiB or this limit if higher.
- Target
- GRAMPS_MEDIA_MAX_BYTES
- Default
- 5242880
- Value
- 5242880
Allow media bytes for Gramps records marked private.
- Target
- GRAMPS_MEDIA_ALLOW_PRIVATE
- Default
- false
- Value
- false
Optional host folder containing files to upload. Also enable Media Resources and set Media Upload Directories to /uploads.
- Target
- /uploads
Absolute container folders allowed for media uploads, separated by colons; use /uploads with the Media Upload Folder mapping. Uploads also require Enable Media Resources=true.
- Target
- GRAMPS_MEDIA_UPLOAD_DIRS
Experimental chat attachment uploads: comma-separated trusted host names (including subdomains), without scheme, port or path. HTTPS and Enable Media Resources are required. Blank disables this source.
- Target
- GRAMPS_MEDIA_UPLOAD_HOSTS
Maximum size in bytes for a file uploaded by create_media or update_media (default 50 MiB).
- Target
- GRAMPS_MEDIA_UPLOAD_MAX_BYTES
- Default
- 52428800
- Value
- 52428800
Server log level: Trace, Debug, Information, Warning, Error, Critical, or None. Debug and Trace log genealogy data from API bodies.
- Target
- GRAMPS_LOG_LEVEL
- Default
- Information
- Value
- Information
Host port mapped to container port 8080 (MCP endpoint at /mcp).
- Target
- 8080
- Default
- 8080
- Value
- 8080