gramps-web-mcp

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

Internet access to pull the container image and reach your Gramps Web API URL.
Overview
MCP server for Gramps Web — structured AI agent access to your family tree over HTTP.

gramps-web-mcp

License: AGPL v3 .NET 10 MCP server version CI 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 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
  • History and undo — get_recent_changes shows the edit history, or who changed each field of one record and what it held before; undo_change reverts one transaction. 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

  1. 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.
  2. Double-click it, or drag it into the Claude Desktop window.
  3. Enter your Gramps Web URL, username, password/token, and tree UUID.
  4. Leave Read-only mode enabled for your first session; disable it only when you want Claude to create or edit records.
  5. 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 all

Links

Details

Repository
ghcr.io/scormave/gramps-web-mcp:2.11.2
Last Updated2026-11-22
First Seen2026-06-24

Runtime arguments

Network
bridge
Privileged
false

Template configuration

Gramps API URLVariable

Base URL of your Gramps Web instance (no trailing slash).

Target
GRAMPS_API_URL
Value
https://gramps.example.com
Gramps UsernameVariable

Gramps Web API username; use with Gramps Password, or leave blank when using a refresh token.

Target
GRAMPS_USERNAME
Gramps PasswordVariable

Gramps Web API password; use with Gramps Username, or leave blank when using a refresh token.

Target
GRAMPS_PASSWORD
Gramps Refresh TokenVariable

Alternative to username and password, including when local password authentication is disabled. Takes precedence if both methods are set.

Target
GRAMPS_REFRESH_TOKEN
Gramps Tree IDVariable

Tree UUID on the Gramps Web server.

Target
GRAMPS_TREE_ID
Read Only ModeVariable

Set to true to publish only read tools and block direct create, update, and delete calls.

Target
GRAMPS_READ_ONLY
Default
false
Value
false
ConfirmationVariable

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
Require User InteractionVariable

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
MCP API KeyVariable

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
MCP Allowed OriginsVariable

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
MCP StatelessVariable

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
Mutation SerializeVariable

Serialize create, update, and delete HTTP calls in-process to reduce SQLite lock errors.

Target
GRAMPS_MUTATION_SERIALIZE
Default
true
Value
true
Mutation Min Interval MSVariable

Optional minimum milliseconds between mutation HTTP calls (0 disables pacing).

Target
GRAMPS_MUTATION_MIN_INTERVAL_MS
Default
0
Value
0
Enable Media ResourcesVariable

Enable read_media, binary media resources, and uploads via create_media or update_media filePath.

Target
GRAMPS_MEDIA_RESOURCES_ENABLED
Default
false
Value
false
Media Max BytesVariable

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 Private MediaVariable

Allow media bytes for Gramps records marked private.

Target
GRAMPS_MEDIA_ALLOW_PRIVATE
Default
false
Value
false
Media Upload FolderPathro

Optional host folder containing files to upload. Also enable Media Resources and set Media Upload Directories to /uploads.

Target
/uploads
Media Upload DirectoriesVariable

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
Media Upload HostsVariable

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
Media Upload Max BytesVariable

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
Gramps Log LevelVariable

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
MCP HTTP PortPorttcp

Host port mapped to container port 8080 (MCP endpoint at /mcp).

Target
8080
Default
8080
Value
8080