Gramps Web MCP Server

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 34 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
• Undo and confirmation — undo_change reverts one transaction of the edit history; it and delete_object 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, and citing facts
• 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.

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:

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:

Configuration describes every setting, including write pacing for SQLite, confirmation dialogs, media limits, transports, browser origins and logging.

Documentation

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.

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.