Gramps Evidence

What Gramps Evidence MCP server does

The Gramps Evidence MCP server connects an MCP-compatible AI client to a Gramps Web family tree. It supports creating and editing genealogical records, including people, families, events, names, places, repositories, sources, citations, notes, media, URLs, attributes, and DNA matches. The write operations are designed around evidence: facts can be created with citations, parent-child links can have their own citations, and citations can be updated, moved, or removed.

The server also provides a read-only reference layer for legacy GEDCOM exports. These files are treated as hints rather than authoritative data, so they can be consulted without directly changing the Gramps Web tree. Audit and query functionality helps locate unsourced facts, backlinks, possible duplicates, and other records that need review.

How it works

Communication with the genealogy data happens over the Gramps Web REST API, also known as gramps-webapi. The server does not open Gramps database files or import Gramps desktop modules. Gramps Web remains the database owner, allowing the web interface and MCP client to work against the same API-managed tree.

The default transport is stdio: an MCP client starts the server as a local subprocess. HTTP transport is also available for remote clients. Remote deployments require a reachable public HTTPS endpoint and an authentication layer outside the server; the README specifically warns against exposing the HTTP service without authentication.

Evidence operations preserve relationships between records. For example, an existing event can be shared with another person through an event reference, while person-specific details such as age can remain on that reference. Removing a citation deletes it when it becomes orphaned, except when it protects attached notes or media; those can be moved to another citation with carry_to.

Setup and configuration

A running Gramps Web instance and uv are required. Install or run the server with:

uvx gramps-evidence-mcp

Create a dedicated Gramps Web user with at least the editor role for write access. Then configure the API URL, username, and password in the MCP client's environment. A TOML file can hold non-secret settings such as the privacy option and legacy GEDCOM reference paths; credentials should remain in environment variables.

The main variables are GRAMPS_MCP_API_URL, GRAMPS_MCP_USERNAME, and GRAMPS_MCP_PASSWORD. GRAMPS_MCP_CONFIG selects the TOML file, while GRAMPS_MCP_TRANSPORT, GRAMPS_MCP_HOST, and GRAMPS_MCP_PORT control HTTP operation. The bundled Docker Compose setup can run a local Gramps Web stack with persistent data and media directories, but an existing Gramps Web deployment can be used instead.

Tools and capabilities

The Gramps Evidence MCP server includes tools for:

• Creating and editing people, families, events, alternate names, child relationships, and family links.
• Creating sources, repositories, places, notes, media, attributes, URLs, and DNA-match records.
• Adding, reusing, citing, updating, moving, and removing citations.
• Attaching media and notes while checking whether the requested attachment was actually verified.
• Finding unsourced facts, backlinks, duplicates, and records through query operations.
• Reading legacy GEDCOM reference files without treating them as sources of truth.
• Optionally processing document images through ocr_media with configured Transkribus credentials and page budgets.

Updates preserve record identity and, where specified, existing citations, notes, privacy settings, or birth order. The server validates some values against the tree's vocabulary and rejects duplicate DNA-match records or unparseable segment data.

Limitations and notes

The Gramps Evidence MCP server is an independent project and is not made, endorsed, or supported by the Gramps project. It requires Gramps Web; it is not a direct client for a Gramps desktop database file. Desktop and web workflows should use export/import rather than pointing both applications at the same database file.

Privacy filtering for living people is enabled by default and can be changed through configuration. The HTTP service does not provide its own authentication, so remote deployments need protection before being exposed to the internet. Legacy GEDCOM data may be incomplete or unsourced and is deliberately presented as untrusted reference material.

Some optional handwriting-processing features require a Transkribus Scholar plan or above, paired Transkribus credentials, and a configured page budget. The server's write model reduces unsupported claims but cannot replace human review of genealogical evidence.