Gramps MCP Server

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.

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, 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?
• What it provides
• Getting started
  • Prerequisites
  • 1. Install
  • 2. Configure credentials
  • 3. Register with your MCP client
• Prompt examples
• Multiple instances (base URLs)
• Tool reference
• Data & safety notes
• Contributing
• Limitations
• Support
• License

Why another Gramps MCP server?

Other Gramps MCP servers already exist:

• Knuckles-Team/gramps-mcp — 35 action-routed tools, A2A agent, OTEL telemetry, single GRAMPS_URL
• cabout-me/gramps-mcp — 16 tools, AGPL-3.0, Docker Compose based, HTTP-first
• Scormave/gramps-web-mcp — 57 tools + 6 resources, .NET, multi-transport, read-only mode
• 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:

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

• 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. 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.

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.

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

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

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  ghcr.io/oliverhruby/gramps-mcp:latest

Version tags are also available (for example v0.1.0) if you prefer pinned images.

Build locally from source (fallback):

docker build -t gramps-mcp-full .

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  gramps-mcp-full

The container uses the same environment variables described in Configure credentials. It also includes a HEALTHCHECK (stdio process liveness by default; local TCP check in HTTP transport modes).

For HTTP transports, set optional runtime vars:

• MCP_TRANSPORT: stdio (default), sse, or streamable-http
• MCP_HOST: bind host (default 127.0.0.1)
• MCP_PORT: bind port (default 8000)
• MCP_API_KEY: optional bearer token for HTTP auth

When MCP_API_KEY is set, HTTP requests must include Authorization: Bearer <key>. If MCP_API_KEY is not set, HTTP endpoints are unauthenticated. For production, prefer proper authentication and TLS via a reverse proxy or API gateway.

pyproject.toml pins mcp<2 (the stable FastMCP v1 API). mcp 2.x renamed FastMCP to MCPServer and changed the API surface; this server targets the FastMCP v1 API for simplicity and stability.

Development from source

Use this if you are contributing or debugging locally.

Requirements: Python 3.10+.

git clone https://github.com/oliverhruby/gramps-mcp.git
cd gramps-mcp
pip install -e . pytest

2. Configure credentials

Either set environment variables or pass them at runtime. Point the server at your Gramps Web instance(s) and account:

# Windows (persistent, per-user)
setx GRAMPS_MCP_INSTANCES "https://gw.example.com,https://gw2.example.com"   # one or more base URLs
setx GRAMPS_MCP_USERNAME "your_username"
setx GRAMPS_MCP_PASSWORD "your_password"

# macOS / Linux
export GRAMPS_MCP_INSTANCES="https://gw.example.com,https://gw2.example.com"
export GRAMPS_MCP_USERNAME="your_username"
export GRAMPS_MCP_PASSWORD="your_password"

Single instance? Just set the base URL plus GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD. Login is lazy — the server starts without credentials and logs in on first use via POST /api/token/.

Multiple instances? Add a comma-separated GRAMPS_MCP_INSTANCES list. Login happens per instance api/token/ (default on first use). Alternatively, set GRAMPS_MCP_TOKENS (comma-separated, aligned with GRAMPS_MCP_INSTANCES) to seed pre-issued JWTs for each instance.

Other knobs: GRAMPS_MCP_TIMEOUT (read timeout seconds, default 60), GRAMPS_MCP_INSECURE=1 (skip TLS verification for self-signed servers), GRAMPS_MCP_READONLY=1 (run all tools in read‑only mode; write actions manage_*, merge_objects, manage_import, manage_export, etc. are rejected).

3. Register with your MCP client

opencode — add to ~/.config/opencode/opencode.json (or opencode.jsonc):

{
  "mcp": {
    "gramps": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "gramps-mcp-full"],
      "env": {
        "GRAMPS_MCP_INSTANCES": "{env:GRAMPS_MCP_INSTANCES}",
        "GRAMPS_MCP_USERNAME": "{env:GRAMPS_MCP_USERNAME}",
        "GRAMPS_MCP_PASSWORD": "{env:GRAMPS_MCP_PASSWORD}"
      }
    }
  }
}

Put credentials in your shell/environment (or a .env) and reference them with {env:VAR}, or hardcode them under env: directly. uvx will auto-provision the package the first time; it must be on your PATH.

Claude Desktop / Cursor — use claude_desktop_config.json / .mcp.json with a mcpServers entry in the standard shape, pointing command/args at the venv python and the gramps_mcp.py path, plus an env block with your credentials.

After editing client config, restart the client so the MCP server is loaded.

Prompt examples

Multiple instances (base URLs)

Each Gramps Web instance keeps its own session. Two ways to configure:

A) Environment (recommended). Set GRAMPS_MCP_INSTANCES (comma-separated base URLs) plus shared GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD — the server logs into each instance lazily on first use:

setx GRAMPS_MCP_INSTANCES "https://gw.example.com,https://gw2.example.com"   # Windows
export GRAMPS_MCP_INSTANCES="https://gw.example.com,https://gw2.example.com" # macOS / Linux

get_instances     # lists both base URLs + login status per instance

Each data tool targets the active instance; every instance logs in lazily on its first use via api/token/.

B) Pre-issued JWTs. Set GRAMPS_MCP_TOKENS (comma-separated) aligned with GRAMPS_MCP_INSTANCES — sessions are seeded directly, no on-demand api/token/ login.

Single instance? Just GRAMPS_MCP_INSTANCES + USERNAME + PASSWORD. For several, add them to the comma-separated list (auto-login) or seed GRAMPS_MCP_TOKENS.

Tool reference

✅ write / 💡 read labels come from each tool's docstring (AGENTS.md rule 4).

Data & safety notes

• Most tools have both read and write paths via action=. The write actions (marked ✅ above) mutate real Gramps tree data — use them with care and prefer dry-runs where available (manage_import dry-run, export preview) before destructive operations.
• merge_objects defaults to phoenix survival (the surviving object keeps its handle); pass the appropriate option for titanic survival. There is no undo — consider a manage_transaction snapshot or an export backup beforehand.
• manage_transaction applies raw DB payloads; mistakes are undoable via action="undo" with the returned transaction id, but the tree is otherwise mutated in place.
• The live e2e suite touches real accounts and real data. It never runs in public CI; it never commits, logs, or uploads identities — CI compares only one-way SHA-256 fingerprints, local runs keep exact values in gitignored files.
• Quality gates run on every PR: py_compile, Docker MCP handshake, HTTP auth smoke, Trivy scan, and Glama TDQS watchdog (tool grades + inventory + overall qualityScore).

Contributing

Contributor and maintainer guidance is in CONTRIBUTING.md.

• Contribution workflow and local setup
• Architecture and implementation details
• Release process (PyPI, GitHub Releases, GHCR, MCP Registry)
• CI quality gates and the Glama TDQS watchdog
• Convention: keep the 4 sync points in lockstep when adding/removing tools (quality-gates tool floor, GLAMA_EXPECTED_TOOLS, README tool table + count, tests/e2e/test_manifest.py)

Limitations

• Depends on the official Gramps Web API. Field coverage follows the upstream gramps-project/gramps-web-api REST schema; object payloads use Gramps handle/gramps_id conventions.
• Write tools mutate real data with no confirmation layer. Never run destructive tool-calls you don't understand; the server does not add an extra confirmation prompt on top of the API.
• Auth lives for the process lifetime. Sessions are created lazily per instance via api/token/ and refreshed on demand; it is not a browser-style persistent login.
• Media OCR / face detection depend on optional Gramps Web services. When the instance doesn't enable them, those manage_media features degrade to upload/download only.
• Single-tree license constraints. Gramps Web's free tier historically gates multi-user/tree features; administration tools (manage_user, some manage_tree actions) require a license tier that exposes them.
• MCP_API_KEY only protects the HTTP transport. For production, terminate TLS and authenticate via a reverse proxy in front of the streamable-HTTP endpoint.

Support

If you like this project and want to support or request a feature, send me a beer, it keeps my mind relaxed and ideas will come :-)

License

MIT © Oliver Hrubý

This project is not affiliated with or endorsed by the Gramps project or the authors of gramps-web-api. Gramps is a trademark of its respective owner(s).