Gramps Evidence MCP server

gramps-evidence-mcp

<!-- mcp-name: io.github.ianderso/gramps-evidence-mcp -->

An MCP server that gives an AI assistant read/write access to a Gramps genealogy tree, plus a read-only "reference layer" over legacy GEDCOM exports.

89 tools, built around evidence discipline. The premise is that an assistant turned loose on a family tree will happily invent a plausible ancestor, so the write paths here are shaped to make every claim carry its source: facts are created with citations attached, uncite deletes what it orphans, parent-child links are cited independently because one citation object cannot carry two confidences, and an audit set — listunsourcedfacts, getbacklinks, findduplicates, and server-side queries through queryobjects and queryrecords — exists to find the places where that discipline slipped.

Legacy trees (Ancestry / FamilySearch exports) are consulted through the read-only reference layer as untrusted hints, never a source of truth.

The server is a REST client of Gramps Web (gramps-webapi). It never touches the Gramps database files directly — see How it connects.

Living-person privacy filtering is on by default — see Privacy.

This is an independent project. It is not made, endorsed or supported by the Gramps project.

Contents

• How it connects
• Setup
• Configuration
• Client configuration
• Remote access (Claude web / mobile)
• The evidence model & transactions
• Privacy
• Tool reference
• Reference layer (legacy GEDCOMs)
• Worked example
• Development
• Limitations

How it connects

The server speaks HTTP to gramps-webapi and never opens the Gramps database files. The API server is the sole owner of the database, so this server and the Gramps Web frontend can both write without contending for the desktop app's exclusive lock. The package imports no gramps.gen.* module and needs no sys.path surgery.

One caveat: side by side means the Gramps Web frontend and this server, both talking to the same gramps-webapi. It does not mean pointing the Gramps desktop app at the same database file that gramps-webapi is serving -- that reintroduces the two-writer problem. Treat the Gramps Web tree as the source of truth and round-trip with the desktop app through export/import.

See docs/ARCHITECTURE.md for the layer breakdown.

Setup

You need a running Gramps Web instance, and uv to run the server.

Option A — you already run Gramps Web

If Gramps Web is already up anywhere you can reach, you don't need the bundled docker-compose. Just point the MCP at it:

lives under …/api.

1. Note the API base URL, e.g. http://gramps.example.org:5000. The REST API

editor; owner also works). From a shell on the Gramps Web host / container:

1. Create a dedicated MCP user with at least the editor role (writes need

gramps-web user add mcp 'A_STRONG_PASSWORD' --fullname 'MCP client' --role 3

(On the official image the wrapper is gramps-web; the underlying command is python3 -m gramps_webapi user add ….)

Configuration).

1. Put the URL + credentials in your environment (see

Shortened. The full README is on GitHub.