gramps-mcp

# Gramps MCP Server

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

[![GitHub release](https://img.shields.io/github/v/tag/oliverhruby/gramps-mcp.svg?sort=semver&label=release)](https://github.com/oliverhruby/gramps-mcp/releases)
[![Quality gates](https://img.shields.io/github/actions/workflow/status/oliverhruby/gramps-mcp/quality-gates.yml.svg?label=quality%20gates)](https://github.com/oliverhruby/gramps-mcp/actions/workflows/quality-gates.yml)
[![Security](https://img.shields.io/github/actions/workflow/status/oliverhruby/gramps-mcp/security.yml.svg?label=security)](https://github.com/oliverhruby/gramps-mcp/actions/workflows/security.yml)
[![Container security](https://img.shields.io/github/actions/workflow/status/oliverhruby/gramps-mcp/container-security.yml.svg?label=container%20security)](https://github.com/oliverhruby/gramps-mcp/actions/workflows/container-security.yml)

## Project

A Model Context Protocol (MCP) server that exposes the full functionality of the Gramps Web API to AI agents such as opencode, Claude, Cursor and any other MCP client. It is published on PyPI as [`gramps-mcp-full`](https://pypi.org/project/gramps-mcp-full/).

Gramps is a free, open-source genealogy program, and **Gramps Web** ships a REST API (`gramps-web-api`) that lets you read and operate a family tree — people, families, events, places, sources, citations, notes, media, repositories and tags, plus genealogy compute (merge, timelines, relations, living status, DNA), import/export, reports, transactions and server administration.

This server lets your agent query and operate a Gramps tree directly: full CRUD for all object types, full-text/semantic search, merge objects (phoenix/titanic survival), timelines, relationships, alive estimates, DNA match analysis, a media pipeline (binary upload, file download, thumbnails, OCR, face detection), GEDCOM / Gramps XML import and export with privacy filters, report generation, raw transactions, and admin over users, trees, bookmarks and type vocabularies — including **multiple instances** (one or more Gramps Web base URLs, each with token/JWT auth).

> **⚠️ Official API, mutable data.** Unlike the EduPage server (which reverse-engineers undocumented endpoints), this uses the **official, documented** Gramps Web REST API — [`gramps-web-api`](https://github.com/gramps-project/gramps-web-api), maintained under the `gramps-project` organization with a published OpenAPI spec at <https://gramps-project.github.io/gramps-web-api/>. Use read-only features freely; use the write features (`manage_*`, `merge_objects`, `manage_import`, `manage_transaction`, …) carefully — they mutate real tree data.

---

## Table of Contents

- [Why another Gramps MCP server?](#why-another-gramps-mcp-server)
- [What it provides](#what-it-provides)
- [Getting started](#getting-started)
  - [Prerequisites](#prerequisites)
  - [1. Install](#1-install)
  - [2. Configure credentials](#2-configure-credentials)
  - [3. Register with your MCP client](#3-register-with-your-mcp-client)
- [Prompt examples](#prompt-examples)
- [Multiple instances (base URLs)](#multiple-instances-base-urls)
- [Tool reference](#tool-reference)
- [Data & safety notes](#data--safety-notes)
- [Contributing](#contributing)
- [Limitations](#limitations)
- [Support](#support)
- [License](#license)

---

## Why another Gramps MCP server?

Other Gramps MCP servers already exist:

- [`Knuckles-Team/gramps-mcp`](https://github.com/Knuckles-Team/gramps-mcp) — 35 action-routed tools, A2A agent, OTEL telemetry, single `GRAMPS_URL`
- [`cabout-me/gramps-mcp`](https://github.com/cabout-me/gramps-mcp) — 16 tools, AGPL-3.0, Docker Compose based, HTTP-first
- [`Scormave/gramps-web-mcp`](https://github.com/Scormave/gramps-web-mcp) — 57 tools + 6 resources, .NET, multi-transport, read-only mode
- [`Genealogy-MCP/gramps-mcp`](https://gitlab.com/Genealogy-MCP/gramps-mcp) — AGPLv3, GitLab mirror, 32 releases

All are good and I have **no affiliation** with them — they are simply referenced here for honest comparison. They either fragment the surface into many near-identical tools or cover only read-mostly slices of the API.

This project deliberately goes further:

| Capability | Knuckles-Team/gramps-mcp | cabout-me/gramps-mcp | Scormave/gramps-web-mcp | **this project** |
|---|---|---|---|---|
| **Full CRUD** — people, families, events, places, sources, citations, notes, media, repositories, tags | partial (actions) | partial | ✅ | ✅ |
| **One `manage_*` tool per object type** (`action=` get/list/create/update/delete) | ❌ | ❌ | ❌ | ✅ |
| **Genealogy compute** — `merge_objects` (phoenix/titanic), `get_timeline`, `get_relation`, `get_living` | ❌ | ❌ | partial | ✅ |
| **DNA analysis** — `analyze_dna` (matches, Y-DNA, segment parser) | ❌ | ❌ | ❌ | ✅ |
| **Media pipeline** — binary upload, file download, thumbnails, OCR, face detection | ❌ | partial | partial | ✅ |
| **Import / export** — GEDCOM / Gramps XML with dry-run, restore, privacy filters | import only | import only | export only | ✅ |
| **Reports** — list, generate, download | ❌ | ❌ | ❌ | ✅ |
| **Transactions** — raw apply/undo, history, bulk create/delete | ❌ | ❌ | ❌ | ✅ |
| **Administration** — users, trees (repair/migrate/verify/config), bookmarks, types | partial | ❌ | partial | ✅ |
| **Server metadata** — database, versions, locale, counts, capabilities | ❌ | ❌ | ❌ | ✅ |
| **Multiple instances** — one or more Gramps Web base URLs | ❌ | ❌ | ✅ | ✅ |
| **Auth** — lazy token login `/api/token/` + pre-issued JWTs + refresh | JWT | user/pass | token | ✅ |
| **Read-only mode** | ❌ | ❌ | ✅ | ✅ |
| **Quality gates by default** — py_compile, Docker MCP handshake, HTTP auth smoke, Trivy, Glama TDQS watchdog | ❌ | ❌ | ❌ | ✅ |
| **Publishing** — PyPI, GHCR, MCP Registry, Glama | PyPI | Docker Hub/GitHub | GHCR | ✅ |

**Key differentiators:**

- **Tight toolset with discriminating parameters.** 27 tools (vs 57 fragmented or 35 action-routed): every object type is served by one `manage_*` tool with an `action=` parameter, mirroring the canonical `get_timetable`/`login` family design.
- **Genealogy-specific compute.** Merge with phoenix/titanic survival, chronological timelines, relationship degrees/paths, living status with probable dates, and a real DNA segment parser — not just object storage.
- **Full write surface.** Import/export with privacy filters and dry-run, report generation, raw transactions, user/tree/bookmark/type administration — the other servers don't cover these.
- **Production-ready.** Multi-instance + token/JWT auth with refresh, quality gates on every PR (lint → Docker handshake → HTTP auth smoke → Trivy → Glama TDQS watchdog), and OIDC publishing to PyPI, GHCR and the MCP Registry.

---

## What it provides

A single MCP server exposing **27 tools** (published on PyPI as [`gramps-mcp-full`](https://pypi.org/project/gramps-mcp-full/)):

- **Core** — `ping` (health), `get_instances` (configured Gramps Web base URLs)
- **Objects (full CRUD)** — `manage_person`, `manage_family`, `manage_event`, `manage_place`, `manage_source`, `manage_citation`, `manage_note`, `manage_media`, `manage_repository`, `manage_tag` — each takes one `action=` (`get`, `list`, `create`, `update`, `delete`); `manage_media` also handles binary upload, file download, thumbnails, OCR and face detection
- **Search & compute** — `search` (full-text/semantic, filterable by object type), `merge_objects` (phoenix survives by default, titanic optional), `get_timeline` (person/family/tree), `get_relation` (degree + paths), `get_living` (status or probable dates), `analyze_dna` (matches, Y-DNA, segment parser)
- **Data management** — `manage_import` (list importers, import file with dry-run, restore backup), `manage_export` (list exporters, export GEDCOM/Gramps XML/CSV with privacy filters), `manage_report` (list/generate/download), `manage_transaction` (apply/undo raw payloads, history, bulk create/delete)
- **Administration** — `manage_user`, `manage_tree` (create/update/disable/enable/repair/migrate/verify/config), `manage_bookmark` (per-namespace), `manage_type` (default + custom vocabularies), `get_server_info` (database, versions, locale, object counts, capabilities)

---

## Getting started

You need an MCP-capable client (opencode, Claude Desktop, Cursor, etc.) and a reachable Gramps Web instance (base URL + a user account with the needed permissions).

### 1. Install

If you are using an AI coding client, a simple prompt is often enough to get started, for example: "Install the Gramps MCP as described in this GitHub repository oliverhruby/gramps-mcp". Most MCP-capable clients can then guide you through the available setup options.

**Option A — from MCP Registry (recommended, one-click in VS Code / GitHub Copilot)**

The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/). In VS Code or GitHub Copilot, search for "Gramps MCP" and install with one click. Or use the direct deeplink: `mcp://install/io.github.oliverhruby/gramps-mcp`

**Option B — from PyPI**

Use this for normal usage with a released version.

Requirements: `uv` for `uvx`, or Python **3.10+** for `pip`.

```bash
uvx gramps-mcp-full
# or, if you prefer pip (into whatever environment your MCP client uses):
pip install gramps-mcp-full
```

`uvx` runs the package without a persistent install. If `uvx` is unavailable, install `uv` first (`pip install uv` or `winget install astral-sh.uv`).

**Option C — from GitHub (latest source)**

Use this if you want the latest changes before a PyPI release.

Requirements: `uv` for `uvx`, or Python **3.10+** for `pip`.

```bash
uvx --from "git+https://github.com/oliverhruby/gramps-mcp.git" gramps-mcp-full
# or
pip install "git+https://github.com/oliverhruby/gramps-mcp.git"
```

**Option D — Docker**

Use this for an isolated container runtime.

Requirements: Docker.

Pull a prebuilt image (recommended):

```bash
docker pull ghcr.io/oliverhruby/gramps-mcp:latest

docker run --rm -i \
  -e GRAMPS_MCP_INS