gramps-evidence-mcp

# gramps-evidence-mcp

[![CI](https://github.com/ianderso/gramps-evidence-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ianderso/gramps-evidence-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/gramps-evidence-mcp?label=pypi)](https://pypi.org/project/gramps-evidence-mcp/)

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

An [MCP](https://modelcontextprotocol.io) 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 — `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](#how-it-connects).

Living-person privacy filtering is **on by default** — see [Privacy](#privacy).

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

---

## Contents

- [How it connects](#how-it-connects)
- [Setup](#setup)
- [Configuration](#configuration)
- [Client configuration](#client-configuration)
- [Remote access (Claude web / mobile)](#remote-access-claude-web--mobile)
- [The evidence model & transactions](#the-evidence-model--transactions)
- [Privacy](#privacy)
- [Tool reference](#tool-reference)
- [Reference layer (legacy GEDCOMs)](#reference-layer-legacy-gedcoms)
- [Worked example](#worked-example-a-person-with-a-cited-birth)
- [Development](#development)
- [Limitations](#limitations)
- [Repository layout](#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](docs/ARCHITECTURE.md) for the layer breakdown.

---

## Setup

You need a running **Gramps Web** instance, and
[`uv`](https://docs.astral.sh/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](#configuration)).

### Option B — run Gramps Web locally with the bundled compose

A ready-to-go stack is in [`docker/docker-compose.yml`](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.

```bash
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:

```bash
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

```bash
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`](.env.example)). Real environment
variables win over the file.

| Var | Meaning |
| --- | --- |
| `GRAMPS_MCP_API_URL` | Base URL of `gramps-webapi`, e.g. `http://gramps.example.org:5000` |
| `GRAMPS_MCP_USERNAME` | The dedicated MCP user |
| `GRAMPS_MCP_PASSWORD` | Its password |
| `GRAMPS_MCP_CONFIG` | Path to the TOML config (default `./gramps_mcp.toml`, from the working directory) |
| `GRAMPS_MCP_EXPOSE_PRIVATE` | Override the TOML `expose_private` flag |
| `GRAMPS_MCP_TRANSPORT` | `stdio` (default) or `http` — see [Remote access](#remote-access-claude-web--mobile) |
| `GRAMPS_MCP_HOST`, `GRAMPS_MCP_PORT` | Where `http` listens (default `127.0.0.1:8090`) |

### TOML file (see [`gramps_mcp.example.toml`](gramps_mcp.example.toml))

```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/`):

```json
{
  "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**:

```bash
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

```bash
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`:

```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:

```yaml
  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