Gramps Evidence

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.

97 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](https://www.grampsweb.org/) (`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
• Reading documents: ocr_media
• 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:

   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 ….)

1. 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 4 docker 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-slim

RUN pip install uv ENV GRAMPS_MCP_TRANSPORT=http GRAMPS_MCP_HOST=0.0.0.0 GRAMPS_MCP_PORT=8090 EXPOSE 8090 CMD ["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 97 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 r