Gramps Evidence

gramps-evidence-mcp

[CI] [PyPI]

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.

83 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 — list_unsourced_facts, get_backlinks, find_duplicates, and server-side queries through query_objects and query_records — 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
• Repository layout

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:

1. Note the API base URL, e.g. http://gramps.example.org:5000. The REST API lives under …/api.
2. Create a dedicated MCP user with at least the editor role (writes need editor; owner also works). From a shell on the Gramps Web host / container:
   bash

   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 ….)
3. Put the URL + credentials in your environment (see Configuration).

Option B — run Gramps Web locally with the bundled compose

A ready-to-go stack is in docker/docker-compose.yml: SQLite backend, bind-mounted data and media directories (a plain directory tree you can copy or back up like any other), and host port 5555 → container 5000. Port 5555 avoids macOS's AirPlay Receiver, which occupies 5000.

docker compose -f docker/docker-compose.yml up -d

Then create the first owner (browser wizard at http://localhost:5555, or CLI) and the dedicated MCP editor user:

docker compose -f docker/docker-compose.yml exec grampsweb \    gramps-web user add owner 'OWNER_PW' --fullname 'Owner' --role 4docker compose -f docker/docker-compose.yml exec grampsweb \    gramps-web user add mcp 'MCP_PW' --fullname 'MCP client' --role 3

The tree named by GRAMPSWEB_TREE (default MyTree) is created on first start.

Install the MCP server

uvx gramps-evidence-mcp

That runs the server over stdio, which is how an MCP client starts it. You normally put it in the client's configuration (below) rather than running it yourself.

Configuration

Secrets live in the environment; everything else in a TOML file. The TOML file therefore never contains credentials.

Environment variables

Set them in the client configuration, or in a .env file in the directory the server starts in (see .env.example). Real environment variables win over the file.

TOML file (see gramps_mcp.example.toml)

[server]expose_private = false          # see Privacy below
[[reference]]path  = "~/gedcoms/export_one.ged"label = "Ancestry (one branch)"trust = "User-built; many hints unsourced. Verify everything."

A desktop client starts the server in a directory of its own choosing, so give GRAMPS_MCP_CONFIG as an absolute path.

Client configuration

Claude Desktop — add to claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/):

{  "mcpServers": {    "gramps": {      "command": "uvx",      "args": ["gramps-evidence-mcp"],      "env": {        "GRAMPS_MCP_API_URL": "http://gramps.example.org:5000",        "GRAMPS_MCP_USERNAME": "mcp",        "GRAMPS_MCP_PASSWORD": "MCP_PW",        "GRAMPS_MCP_CONFIG": "/path/to/gramps_mcp.toml"      }    }  }}

Claude Code:

claude mcp add gramps \    -e GRAMPS_MCP_API_URL=http://gramps.example.org:5000 \    -e GRAMPS_MCP_USERNAME=mcp -e GRAMPS_MCP_PASSWORD=MCP_PW \    -e GRAMPS_MCP_CONFIG=/path/to/gramps_mcp.toml \    -- uvx gramps-evidence-mcp

Any other MCP client that launches stdio servers works the same way: the command is uvx gramps-evidence-mcp, with the variables above in its environment. Restart the client after editing its configuration.

To run from a clone instead, replace uvx gramps-evidence-mcp with uv --directory /path/to/gramps-evidence-mcp run gramps-evidence-mcp.

Remote access (Claude web / mobile)

The configuration above uses the stdio transport: the client launches the server as a local subprocess. Claude web (claude.ai) and the mobile apps can't do that — they connect to a remote server over HTTPS using the Streamable HTTP transport, added as a Custom Connector. Three differences to plan for:

1. Transport must be HTTP, not stdio.
2. Reachability — Anthropic's servers dial out to yours, so it needs a public HTTPS URL. A LAN address like http://192.168.1.50:5000 won't work.
3. Auth — it's write access to a database of living relatives, so it must sit behind authentication. The server has none of its own. Never expose it authless.

If you don't specifically need a browser/phone, a desktop client already gives you the same models with this server working locally (stdio, no public exposure). The steps below are only for genuine remote access.

1. Serve it over HTTP

GRAMPS_MCP_TRANSPORT=http uvx gramps-evidence-mcp

That serves the MCP endpoint at http://127.0.0.1:8090/mcp; GRAMPS_MCP_HOST and GRAMPS_MCP_PORT change where. The other GRAMPS_MCP_* variables apply as before.

Bound to a loopback address, the server accepts only requests whose Host is localhost or 127.0.0.1 — the MCP SDK's protection against DNS rebinding. A tunnel or proxy on the same machine must therefore send Host: localhost (cloudflared's httpHostHeader setting does this). In a container, bind 0.0.0.0 instead, as below, and let the container network do the isolating.

2. Deploy it next to Gramps Web

Run it in a container on the same host as Gramps Web so it talks to the API over the internal network. A minimal Dockerfile:

FROM python:3.13-slimRUN pip install uvENV GRAMPS_MCP_TRANSPORT=http GRAMPS_MCP_HOST=0.0.0.0 GRAMPS_MCP_PORT=8090EXPOSE 8090CMD ["uvx", "gramps-evidence-mcp"]

Add it to your Gramps Web compose (same network), pointing at the API by service name and reading secrets from the environment:

  gramps_evidence_mcp:    build: /path/to/dockerfile-dir    restart: unless-stopped    environment:      GRAMPS_MCP_API_URL: "http://grampsweb:5000"   # internal service name      GRAMPS_MCP_USERNAME: "mcp"      GRAMPS_MCP_PASSWORD: "${MCP_PW}"    # no host port needed if the tunnel (below) runs in the same compose network

3. Expose it publicly with TLS

A reverse tunnel avoids port-forwarding and gives you TLS and a stable hostname. Any of these work:

• Cloudflare Tunnel — run cloudflared alongside the server and route a hostname such as https://gramps-mcp.example.org → http://gramps_evidence_mcp:8090.
• Tailscale Funnel — public HTTPS over your own tailnet.
• ngrok http 8090 for a quick throwaway test.

Or terminate TLS yourself with any reverse proxy in front of port 8090.

4. Put auth in front

claude.ai custom connectors speak the MCP OAuth 2.0 flow. Put an identity proxy in front of the tunnel hostname — Cloudflare Access, Authelia, oauth2-proxy and similar all tie into the OAuth flow the connector expects. The server does not authenticate callers itself; see docs/ROADMAP.md.

5. Add the connector in claude.ai

Settings → Connectors → Add custom connector → paste https://gramps-mcp.example.org/mcp, complete the auth prompt, and the 83 tools appear in chat. (Custom connectors require a paid Claude plan; on Team/Enterprise an admin may need to enable them.)

Security reminder: this endpoint can create, edit, and delete records in a tree containing living people. Keep it behind auth, prefer a private tunnel over an open port, and consider a Gramps Web user with a read-only role if you only need lookups remotely — the server's write tools then fail with a permission error instead of writing.

The evidence model & transactions

The server enforces the Gramps evidence model:

Repository  →  Source  →  Citation  →  fact (Event / Attribute)

Every fact-recording write requires a citation. You either reference an existing citation/source or create one inline. The only way to record a fact without a citation is to explicitly pass require_citation=False, which stamps the event with an UNSOURCED=true attribute so list_unsourced_facts can find it later. Confidence levels map to Gramps' 0–4 scale (very_low, low, normal, high, very_high).

How writes map to DbTxn transactions

gramps-webapi wraps every object create/update in its own server-side DbTxn (labelled New Person, Edit Event, …), so all writes go through proper transactions and stay in Gramps' undo history. A composite operation (e.g. add_person with a cited birth) is performed as an ordered sequence of these object writes — source → citation → event → person — with references wired up as it goes.

Design note (documented deviation): gramps-webapi also offers a raw POST /api/transactions/ endpoint that can bundle several objects into a single DbTxn with a custom description. We intentionally don't use it, because that endpoint bypasses the server-side helpers that (a) auto-assign handle and gramps_id and (b) coerce English type strings ("Birth") into internal Gramps type dicts. Using it would force this client to reimplement Gramps' ID allocation and type internals and to invent gramps_ids, risking a desynced ID counter. The per-object-transaction approach is safer and keeps undo coherent; the trade-off is that one logical add appears as a few undo entries rather than one.

Privacy

The tree contains living people. With expose_private = false (the default), bulk output leaves out anyone private or probably living:

• Probably living means born less than 110 years ago with no recorded death — or with neither a birth nor a death recorded, which errs toward privacy. A death event counts as recorded even without a date. 110 is the conventional genealogical "presumed dead" cutoff; it does not permanently hide clearly historical people.
• Private means the Gramps private flag, on a record of any type.

What that means tool by tool:

A lookup by id is not filtered. get_person, get_object, the other typed getters, and list_unsourced_facts for one named person answer in full. This is a personal tool the tree's owner runs against their own data: the goal is to prevent accidental bulk leakage — search dumps, tree walks, shared reports — not to lock the owner out. Asking for one record by id is a deliberate act.

Writes are never filtered. Adding, citing, editing, merging and deleting work on living and private people like anyone else.

Ask, and one call shows everyone. Every tool in the table takes include_private. Passed as true, that call answers in full — living people, private records, Gramps' own report defaults — and the next call is filtered again. It is meant for when you ask for living relatives by name ("list my cousins born after 1950"), and the tool descriptions tell the assistant so. Each use is logged with the tool's name, never the records.

Not filtered, by design or by limitation:

• export_backup is a lossless backup, and a backup that drops living people cannot restore the tree.
• verify_tree returns Gramps' own findings as it words them.
• get_dna_matches answers for the person you name, but each match is another person — usually a living one — identified by handle, with segment data.
• Events, citations, notes and media are judged by their own private flag only. An event row carries no link back to its person, so a living person's birth event is visible to an event query unless the event itself is private.
• Timeline entries are judged by their person, not by the event's own private flag, which the timeline endpoint does not report.
• A stub still says that a record matched. A query for a name and a birth year that returns a stub confirms that the id is a person fitting both. The filter prevents accidental disclosure, not a determined search.

To turn the filter off for every call instead, set expose_private = true in the TOML file or GRAMPS_MCP_EXPOSE_PRIVATE=true in the client's configuration — for a full audit, or a tree with no living people in it. That reduces privacy protection for everything the assistant reads.

Logs never contain record contents — only handles, ids, and operation names. Request URLs are kept out of the log too, because a query filter travels in one.

Tool reference

83 tools. Every tool that mutates the tree re-fetches the whole object before PUTting it back — edits through service._mutate() — see the keys= trap.

Every tool declares MCP annotations saying whether it only reads, adds, or changes and removes, so a client can approve reads automatically and ask before the rest. 43 tools only read.

Unknown parameters are refused. A misspelt or invented argument is an error that lists the parameters the tool does take. It is not silently dropped, which used to turn query_objects(query=...) — the parameter is gql — into an unfiltered listing of the first 200 objects.

Create

Cite — attaching evidence to a claim

Edit — correcting what is already there

Read

Audit

Ops

Reference layer (read-only, never touches the tree)

Querying with GrampsQL

query_objects filters in the database rather than pulling a collection and sifting it in Python. The syntax has traps, verified against gramps-webapi 3.21.1:

• Equality is a single =. page == "" is a parse error.
• ~ is substring: description ~ "1871".
• .length works on any list: media_list.length = 0.
• A field the object does not have matches nothing, without an error. A zero count can mean a misspelt field.
• type is such a field on events. type = "Birth" matches nothing, silently, on a tree with hundreds of births. Use query_records with event_type instead.
• A source has no citation_list — citations point at sources. Use get_backlinks to find uncited sources. Querying citation_list on sources matched every source on 3.20.1 and matches none on 3.21.1.
• Booleans compare as integers: private = 1, not private = true.

Useful ones:

citations   confidence >= 3 AND page = ""     high-confidence claims with no locatorsources     media_list.length = 0             documents with no image attachedmedia       desc = ""                         media nothing identifies

Every tool has an LLM-facing docstring explaining when to use it, parameter semantics, and good citation practice.

Reference layer (legacy GEDCOMs)

consult_reference searches the GEDCOM files listed in your TOML config and returns, per file, matching individuals and their claimed facts. Crucially, each fact is flagged whether the legacy tree attached a source, with the source text if present — so the assistant can distinguish "Ancestry cites an actual death certificate" from "unsourced guess."

• Parses GEDCOM 5.5.1, including the Ancestry dialect (_APID, _TREE, …). Custom underscore tags are carried through, not choked on.
• Files load lazily and their parsed form is cached on disk (keyed by path/size/mtime), so a big export is parsed once.
• Each file has a trust note surfaced in results.

These are untrusted hints. The intended loop: consult a hint → decide which real record to hunt down → create the fact in the tree citing that record — never copy a hint in as if it were sourced.

Your real GEDCOMs are never committed (.gitignore excludes *.ged except the synthetic test fixture).

Worked example: a person, with a cited birth

You: Add Martha Ellery, female, born 12 Jan 1890 in Columbus, Ohio. I have her birth certificate (Ohio certificate #12345); cite it at very-high confidence.

The assistant calls one tool:

add_person({  "given": "Martha", "surname": "Ellery", "gender": "female",  "birth": {    "type": "Birth",    "date": "12 Jan 1890",    "place": "Columbus, Ohio, USA",    "citation": {      "source_title": "Ohio Birth Certificate #12345",      "page": "certificate no. 12345",      "confidence": "very_high"    }  }})

Behind the scenes the server: creates the Source "Ohio Birth Certificate #12345" → creates a Citation on it (page + very-high confidence) → finds or creates the Place "Columbus, Ohio, USA" → creates the Birth Event (dated, placed, carrying the citation) → creates the Person referencing that event as their primary birth. It returns the new gramps_id (e.g. I0001).

Ask list_unsourced_facts any time to see what still needs a source. If you add a fact you can't yet source, pass require_citation=false and it'll be tagged UNSOURCED for that audit list.

Development

git clone https://github.com/ianderso/gramps-evidence-mcpcd gramps-evidence-mcpuv sync --extra devuv run pytest

The suite runs against an in-memory fake of gramps-webapi served through respx, so it needs no Gramps Web instance, and it fails any test that tries to open a real connection. It exercises the tool surface the way a client calls it: every tool's schema, the refusal of unknown arguments, the whole-object write rule across every editing tool, the privacy filter on each bulk output, and the error envelope every tool returns instead of raising.

CONTRIBUTING.md says what a change is expected to carry.

Limitations

• Built against gramps-webapi 3.20.1 and 3.21.1 (Gramps 6.0). Your instance's /api/openapi.json is authoritative — check it if a call behaves unexpectedly, and see docs/PITFALLS.md for where the API's behaviour has surprised before.
• No tree selector. On gramps-webapi the tree is bound to the account you authenticate as; no data endpoint takes a tree parameter. To work against a different tree, use credentials belonging to it.
• Type strings ("Birth", "Married") rely on the server's English/locale type coercion. If your instance runs a non-English default locale, prefer canonical English type names.
• search_people, list_unsourced_facts and find_duplicates read whole collections. That suits a personal tree of a few thousand people; they are not built for very large databases.
• get_facts is computed by the server on every call and takes tens of seconds on a tree of under a thousand people; the call is allowed three minutes.

Repository layout

src/gramps_evidence_mcp/    the MCP server  server.py                 tool definitions (the 83 tools) and the entry point  service.py                genealogy operations; edits go through _mutate()  client.py                 gramps-webapi REST client  mapping.py                Gramps object <-> JSON shapes  models.py                 Pydantic input models shared by the tools  privacy.py                living-person assessment and redaction  gedcom_ref.py             read-only reference layer over legacy GEDCOMs  config.py                 env vars + TOMLtests/                      against an in-memory fake; no live server neededdocker/                     docker-compose for a local Gramps Webdocs/  ARCHITECTURE.md           how the server is put together  PITFALLS.md               gramps-webapi behaviours that have cost real data  ROADMAP.md                what is planned (nothing), and what is not

docs/PITFALLS.md is required reading before writing a script against gramps-webapi directly. Every item in it was learned by losing something: a keys= PUT that wiped parent links on 65 families, a citation handle reused across two claims that mis-graded 107 parent-child links, and two concurrent sessions that took the write path down for ~18 hours.