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