Gramps MCP MCP Server

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

**Option E -- one-shot with APM (server *and* bundled skill)**

APM (Agent Package Manager) is an emerging open standard for distributing agent context -- think npm for agent skills, MCP servers and configuration. It is optional: skip it and any option above works exactly as before. If you already use APM (or want to try it), one command installs both pieces this project ships.

1. Install the CLI once. Requirements: git, plus uv for the server runtime.

• Windows: `winget install --id