Gramps MCP
A full-surface MCP server for the official Gramps Web genealogy REST API — it lets an AI agent read and mutate a family tree, run genealogy/DNA compute, do import/export/reports, and administer the Gramps Web server, across one or more instances.
Health & setup:
ping(liveness + version) andget_instances(configured base URLs/scope).Full CRUD on every core object type:
manage_person,manage_family,manage_event,manage_place,manage_source,manage_citation,manage_note,manage_media,manage_repository,manage_tag— each withaction=get/list/create/update/delete, flexible query params (paging, keys, profile, extend, locale).Media pipeline: binary upload from a local path with MIME type, file download, thumbnails by size (square option), OCR text, and face detection.
Search: full-text or semantic/vector search across object types, with type allowlists, sorting, change-date filters, and profile sections.
Genealogy compute:
merge_objects(phoenix survives / titanic absorbed, incl. family-specific options),get_timeline(person/family/tree-wide, generations, event classes),get_relation(relationship degree and all paths),get_living(living verdict or probable dates with tunable heuristics),analyze_dna(matches, Y-DNA clade, raw segment parsing).Import/export:
manage_import(list/info/upload with dry-run and full restore),manage_export(list/info/async run/sync file) as GEDCOM, Gramps XML, CSV, with privacy and living-person filters.Reports:
manage_reportlist/info/run/file/result for PDF, text, web outputs with per-report options and locale.Raw transactions & bulk ops:
manage_transactionapply/undo, history, undo-by-id, bulk create, delete by namespace or handle list.Administration:
manage_user(users incl. password change),manage_tree(create/update/enable/disable/repair/migrate/verify/config),manage_bookmark(per-namespace),manage_type(default + custom type vocabularies).Server metadata:
get_server_info(database, versions, locale, object counts, capabilities, optional surname list).Multi-instance & auth: target any configured Gramps Web base URL per call, with lazy token/JWT login and an optional read-only mode that rejects writes.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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 thegramps-projectorganization 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.
Related MCP server: Gramps Web MCP
Table of Contents
Why another Gramps MCP server?
Other Gramps MCP servers already exist:
Knuckles-Team/gramps-mcp— 35 action-routed tools, A2A agent, OTEL telemetry, singleGRAMPS_URLcabout-me/gramps-mcp— 16 tools, AGPL-3.0, Docker Compose based, HTTP-firstScormave/gramps-web-mcp— 57 tools + 6 resources, .NET, multi-transport, read-only modeGenealogy-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 | ❌ | ❌ | ❌ | ✅ |
Genealogy compute — | ❌ | ❌ | partial | ✅ |
DNA analysis — | ❌ | ❌ | ❌ | ✅ |
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 | 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 anaction=parameter, mirroring the canonicalget_timetable/loginfamily 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 oneaction=(get,list,create,update,delete);manage_mediaalso handles binary upload, file download, thumbnails, OCR and face detectionSearch & 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-fulluvx 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:latestVersion 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-fullThe 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, orstreamable-httpMCP_HOST: bind host (default127.0.0.1)MCP_PORT: bind port (default8000)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.tomlpinsmcp<2(the stable FastMCP v1 API).mcp 2.xrenamedFastMCPtoMCPServerand 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.
Install the CLI once. Requirements:
git, plusuvfor the server runtime.Windows:
winget install --id Microsoft.APM -e(orscoop bucket add apm https://github.com/microsoft/scoop-apm; scoop install apm)macOS / Linux:
brew install apmAny platform with Python 3.10+:
pip install apm-cliOther options: installation docs
Install this package:
apm install oliverhruby/gramps-mcpThis single command:
writes the
uvx gramps-mcp-fullstdio server entry into the MCP config of every harness APM detects (Claude Code.mcp.json, VS Code / GitHub Copilot, Cursor, OpenCode, Codex, Gemini, Windsurf, Kiro, ...); add--target claude(orcodex,cursor, ...) to force one harness;deploys the bundled
person-research-briefskill into that harness's skills directory (.claude/skills/,.agents/skills/, ...).
Verify:
apm mcp list # server registered?apm uninstall oliverhruby/gramps-mcpremoves the package and the deployed skill files, but leaves the MCP server entry it wrote into.mcp.json(and other harness configs) -- delete that entry yourself if you want it gone.
Credentials are never embedded in the package: set GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD (and optionally GRAMPS_MCP_INSTANCES) in your environment before running apm install -- see 2. Configure credentials -- and APM passes them through to the generated server config.
Pinning. Append #<sha> (or #<tag> once a release contains apm.yml) to pin an exact revision and silence APM's "dependency unpinned" warning; without a pin, APM records the resolved commit in apm.lock.yaml. Releases up to v0.2.1 predate the manifest, so use a commit sha until the next release.
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 . pytest2. 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 underenv:directly.uvxwill auto-provision the package the first time; it must be on yourPATH.
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
User prompt | Likely tool call(s) | Expected response |
"Are we connected and logged in?" |
| Server health and the configured Gramps Web instance(s). |
"List all people with birth dates after 1900" |
| A short list of matching people. |
"Show the family tree for person I001" |
| The person's family and chronological timeline. |
"Merge person I002 into I001, keeping I001's data" |
| Merge confirmation (phoenix survival). |
"What is the relationship between person I003 and I020?" |
| Degree of kinship plus the path(s) between them. |
"Is person I005 likely living?" |
| Likely-living verdict or probable birth/death date estimates. |
"Analyze DNA matches for person I010" |
| DNA matches, Y-DNA clade, and parsed segments. |
"Upload a media file for person I012" |
| Media object created; thumbnail + OCR available. |
"Export the tree as GEDCOM with privacy filters" |
| Export file produced and downloadable. |
"Import a GEDCOM file (dry-run first)" |
| Dry-run report, then the import result. |
"Generate a research report for person I018" |
| Report generated and downloadable. |
"Apply a raw transaction to update a source" |
| Transaction applied (and undoable later). |
"List all users, then disable |
| User list and the disabled account. |
"Create a new tree and configure its base URL" |
| New tree created and configured. |
"List all default and custom event/place types" |
| Type vocabularies per object type. |
"Get server metadata" |
| Database, versions, locale, object counts, capabilities. |
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 / Linuxget_instances # lists both base URLs + login status per instanceEach 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 seedGRAMPS_MCP_TOKENS.
Tool reference
Tool | Description | Writes? |
| Health check. | 💡 read |
| List configured Gramps Web instances. | 💡 read |
| CRUD Person records ( | ✅ create/update/delete |
| CRUD Family records (father/mother/children refs maintained upstream). | ✅ create/update/delete |
| CRUD Event records (types from | ✅ create/update/delete |
| CRUD Place records. | ✅ create/update/delete |
| CRUD Source records. | ✅ create/update/delete |
| CRUD Citation records (link to | ✅ create/update/delete |
| CRUD Note records (holds DNA segment strings, prose, etc.). | ✅ create/update/delete |
| CRUD Media + binary upload, file download, thumbnail, OCR, face detection. | ✅ create/update/delete/upload |
| CRUD Repository records. | ✅ create/update/delete |
| CRUD Tag records. | ✅ create/update/delete |
| Full-text or semantic search, filterable by object type. | 💡 read |
| Merge two objects of the same type into one. | ✅ merge |
| Chronological event timeline for a person, family, or whole tree. | 💡 read |
| Compute a genealogical relationship between two people. | 💡 read |
| Estimate whether (or until when) a person is alive. | 💡 read |
| DNA match analysis and raw match-string parsing. | ✅ parse only |
| List importers or import a file (Gramps XML, GEDCOM…); dry-run + restore. | ✅ file/restore |
| List exporters or produce an export (GEDCOM, Gramps XML…); privacy filters. | ✅ run |
| List, configure or generate reports (PDF, text, web…). | ✅ run |
| Apply raw DB transactions, undo history, or bulk create/delete. | ✅ all actions |
| Administer Gramps Web users (create/update/delete/change password). | ✅ all actions |
| Trees: create/update, disable/enable, repair, migrate, verify, config. | ✅ all actions |
| Read or edit bookmarks per object namespace. | ✅ add/remove |
| List Gramps type vocabularies (custom + default) for all object types. | 💡 read |
| Read server, database, locale and object-count metadata. | 💡 read |
✅ 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_importdry-run, export preview) before destructive operations.merge_objectsdefaults to phoenix survival (the surviving object keeps its handle); pass the appropriate option for titanic survival. There is no undo — consider amanage_transactionsnapshot or an export backup beforehand.manage_transactionapplies raw DB payloads; mistakes are undoable viaaction="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 + overallqualityScore).
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-apiREST schema; object payloads use Gramps handle/gramps_idconventions.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_mediafeatures degrade to upload/download only.Single-tree license constraints. Gramps Web's free tier historically gates multi-user/tree features; administration tools (
manage_user, somemanage_treeactions) require a license tier that exposes them.MCP_API_KEYonly 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).
Available Tools
27 toolsanalyze_dnaAInspect
DNA match analysis and raw match-string parsing. Writes: parse only.
Actions:
matches -> GET /people//dna/matches; per-match relationship,
segments, common-ancestor profiles and citation-linked notes.
ydna -> GET /people//ydna; Y-DNA haplogroup clade lineage.
parse -> POST /parsers/dna-match with data = the raw DNA match text
(e.g. 23andMe/Ancestry segment blocks); returns parsed segments.
matches accepts raw=true to include the raw segment strings. Matches
are stored as "DNA" associations plus notes; see manage_person/manage_note.
Args: action: "matches", "ydna" or "parse". handle: Person handle; required for matches and ydna. data: Raw DNA match string; required for parse. raw: If true, include raw segment strings in matches output. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": matches, clade or parsed segments}.
Inputs: action (required), raw, data, handle, +1 more.
get_instancesAInspect
List the configured target instances. Read-only.
Args: (none)
Returns: dict: {"instances": [, ...], "scope": "<value of GRAMPS_MCP_INSTANCES, or 'auto-discovery' when unset>"}.
Inputs: no named parameters.
get_livingAInspect
Estimate whether (or until when) a person is alive. Read-only.
mode=status returns {"living": bool} from /living/;
mode=dates returns probable birth/death date estimates plus an
explanation from /living//dates. Tune the heuristic with the
three optional integer parameters (upstream defaults: 20 / 110 / 20).
Args: handle: Person handle. mode: "status" (default) or "dates". average_generation_gap: Average years between generations (>= 1). max_age_probably_alive: Max age in years still considered alive (>= 1). max_sibling_age_difference: Max sibling age gap tolerated (>= 1). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": }.
Inputs: handle (required), mode, instance, average_generation_gap, +2 more.
get_relationAInspect
Compute a genealogical relationship between two people. Read-only.
Without all, returns the shortest/most direct relationship (relationship
string plus distances). With all=true, lists every possible relationship,
including common ancestors per path. Uses /relations// or
/relations///all with an optional depth cap on generations.
Args: handle1: First person handle. handle2: Second person handle. all: If true, return all possible relationships (and ancestors). depth: Maximum generations to search for a common ancestor (default 15, minimum 2). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": relationship(s)}.
Inputs: handle1 (required), handle2 (required), all, depth, +1 more.
get_server_infoAInspect
Read Gramps Web server, database, locale and object-count metadata. Read-only.
Wraps GET /metadata/: database id/name/type, Gramps + Gramps Web API + QL
versions, locale, per-type object counts, tree researcher info, search
index details, and server capabilities (multi-tree, task queue, OCR,
semantic search, chat, face detection, thumbnails). When surnames is
true, the response additionally lists every surname in the database.
Args: surnames: If true, include the full list of surnames in the database. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": metadata object}.
Inputs: instance, surnames.
get_timelineAInspect
Chronological event timeline for a person, family, or the whole tree. Read-only.
kind=person -> /people//timeline; kind=family ->
/families//timeline; kind=people and kind=families return
tree-wide timelines (no handle). Events can be grouped into generations
(ancestors/offspring), filtered by event class (event_classes via
query), and paged (page/pagesize).
Args: kind: "person", "family", "people" or "families". handle: Person/family handle; required for kinds 'person' and 'family'. page: 1-based page of the event list. pagesize: Events per page. strip: If true, drop empty-valued keys from returned objects. discard_empty: If true, omit placeholder slot rows. omit_anchor: If true, exclude the anchor object's own event row. ratings: If true, include per-event relevance ratings. keys: Comma-delimited subset of object keys to return. skipkeys: Comma-delimited keys to exclude. precision: Significant time components (1-3) for age/span strings. ancestors: Number of ancestor generations to include (person kind). offspring: Number of descendant generations to include (person kind). query: Optional dict of extra timeline params (event_classes, events, relative_events, relatives, first, last, handles, ...). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": [timeline rows]}.
Inputs: kind (required), keys, page, query, +11 more.
manage_bookmarkAInspect
Read or edit bookmarks per object namespace. Writes: add, remove.
Bookmarks are per-user, per-type handle shortcuts. namespace is one of:
citations, events, families, media, notes, people, places, repositories,
sources. action=list_all returns every namespace's bookmarks
(GET /bookmarks/); action=list returns one namespace (GET /bookmarks/);
action=add bookmarks a handle (PUT /bookmarks//, idempotent);
action=remove unbookmarks it (DELETE). Adding validates that the object
exists.
Args: namespace: Bookmark namespace (one of the nine object plurals). action: "list_all", "list", "add" or "remove" (default "list"). handle: Object handle to bookmark/unbookmark; required for add/remove. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": bookmark list or empty}.
Inputs: namespace (required), action, handle, instance.
manage_citationAInspect
Create, read, update or delete Gramps Citation records. Writes: create, update, delete.
action=get lists citations (handle empty) or returns one citation by
handle. action=create posts a full Citation JSON object in data;
action=update PUTs data to /citations/; action=delete removes
it. Citation payload fields: gramps_id, source_handle, date, page,
confidence, note_list, media_list, change, ... . Attach a citation to a
Person/Family/Event by adding its handle to that object's citation_list.
Args: action: The operation, "get", "create", "update" or "delete". handle: Citation handle; required for get-one, update, delete. data: The Citation object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_eventAInspect
Create, read, update or delete Gramps Event records. Writes: create, update, delete.
action=get lists events (handle empty) or returns one event by handle.
action=create posts a full Event JSON object in data; action=update
PUTs data to /events/; action=delete removes it. Event payload
fields: gramps_id, type, date, description, place, citations, notes,
attribute_list, media_list, change, ... . Events are typically referenced
by Person/Family event_ref_list entries.
Args: action: The operation, "get", "create", "update" or "delete". handle: Event handle; required for get-one, update, delete. data: The Event object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_exportAInspect
List exporters or produce an export file (GEDCOM, Gramps XML...). Writes: run.
action=list returns every available exporter (GET /exporters/);
action=info describes one exporter (GET /exporters/);
action=run starts an asynchronous export (POST /exporters//file)
and returns a task reference (poll with manage_transaction or re-call to
fetch); action=file runs a synchronous export (GET /exporters//file)
and returns the file as base64. Exports run on the whole tree unless
filtered; pass options as a dict of query params: compress, living
(IncludeAll/FullNameOnly/LastNameOnly/ReplaceCompleteName/ExcludeAll),
private, person, event, note, reference, sequence, handle, gramps_id,
years_after_death, current_year, locale, include_individuals,
include_children, include_marriages, include_places, include_media,
include_witnesses, translate_headers. Extensions: ged, gramps, gw, csv, etc.
Args: action: "list", "info", "run" or "file". extension: Exporter extension (e.g. 'ged' or 'gramps'); required for info, run, file. options: Dict of export option query parameters (see docstring). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": exporter list, task ref, or base64 file}.
Inputs: action (required), options, instance, extension.
manage_familyAInspect
Create, read, update or delete Gramps Family records. Writes: create, update, delete.
action=get lists families (handle empty) or returns one family by
handle. action=create posts a full Family JSON object in data;
action=update PUTs data to /families/; action=delete removes
it. Family payload fields: gramps_id, father_handle, mother_handle,
child_ref_list, event_ref_list, attribute_list, media_list, note_list,
change, relationship, ... . Creating a family rewrites its parents' and
children's person records, so it requires edit + add permissions upstream.
Args: action: The operation, "get", "create", "update" or "delete". handle: Family handle (e.g. 'F0001'); required for get-one, update, delete. data: The Family object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_importAInspect
List importers or import a family tree file (Gramps XML, GEDCOM...). Writes: file, restore.
action=list returns every available importer (GET /importers/);
action=info describes one importer (GET /importers/);
action=file uploads file_path to /importers//file (raw body,
extension picks the importer) and returns the import counts;
action=restore resets the tree to match an uploaded Gramps backup via
/importers//file/restore (replaces all content; requires batch
delete permission). Use dry_run=true on file/restore to preview counts and
changes without touching the tree. Extensions: gramps, gpkg, ged, gedcom,
csv, etc., depending on installed plugins.
Args: action: "list", "info", "file" or "restore". extension: Importer extension (e.g. 'gramps' or 'ged'); required for info, file, restore. file_path: Local path of the file to upload (required for file/restore). dry_run: If true, compute counts/summary without importing (file/restore). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": importer list or import summary}.
Inputs: action (required), dry_run, instance, extension, +1 more.
manage_mediaAInspect
Manage Gramps Media objects and their files. Writes: create, update, delete, upload.
Standard CRUD via /media/ plus binary operations:
get/create/update/delete -> as in manage_person (GET/POST/PUT/DELETE).
upload -> POST /media/ streaming file_path bytes with
mime_type (required); the API computes the
checksum and creates the Media row.
file -> GET /media//file; returns base64 bytes.
thumbnail -> GET /media//thumbnail/; returns
base64 image; pass {"square": true} in query.
ocr -> GET /media//ocr; returns OCR text.
face_detection -> GET /media//face_detection; returns
detected/test faces (see upstream for params).
Repeat action for repeated sub-actions; 'create' accepts a Media JSON body
in data (needs an already-uploaded file), while 'upload' bulk-loads a
local file. Consider merge_objects for duplicate media.
Args: action: "get", "create", "update", "delete", "upload", "file", "thumbnail", "ocr" or "face_detection". handle: Media handle; required for get-one, update, delete, file, thumbnail, ocr, face_detection. data: The Media object for create/update (required for those). query: Optional dict of extra query-string parameters (e.g. {"square": true}). file_path: Local file path for the 'upload' action (required there). mime_type: MIME type of the upload (e.g. 'image/jpeg'); required for 'upload'. size: Thumbnail target size in pixels (required for 'thumbnail'). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"} where binary results carry base64/mimetype.
Inputs: action (required), data, size, query, +4 more.
manage_noteAInspect
Create, read, update or delete Gramps Note records. Writes: create, update, delete.
action=get lists notes (handle empty) or returns one note by handle.
action=create posts a full Note JSON object in data; action=update
PUTs data to /notes/; action=delete removes it. Note payload
fields: gramps_id, type, text, format, note_list, change, ... . Notes are
referenced by other objects' note_list fields; DNA match segment strings
live in notes (see analyze_dna).
Args: action: The operation, "get", "create", "update" or "delete". handle: Note handle; required for get-one, update, delete. data: The Note object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_personAInspect
Create, read, update or delete Gramps Person records. Writes: create, update, delete.
action=get lists people (handle empty, paginated) or returns one person
(handle set, ?profile=&extend= via query). action=create posts a
full Person JSON object in data (handles are assigned by the server).
action=update PUTs data to /people/; action=delete removes it.
Person payload fields follow the Gramps schema (gramps_id, gender,
primary_name, names, event_ref_list, family_list, person_ref_list,
attribute_list, media_list, address_list, url_list, note_list, change, ...).
Args: action: The operation, "get", "create", "update" or "delete". handle: Person handle (e.g. 'P0001'); required for get-one, update, delete. data: The Person object for create/update (required for those). query: Optional dict of extra query-string parameters (e.g. {"page": 1, "pagesize": 20, "keys": "handle,name", "strip": true, "profile": "all", "extend": "all", "locale": "en"}). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status": , "url": , "data": <object(s) | transaction>}.
Inputs: action (required), data, query, handle, +1 more.
manage_placeAInspect
Create, read, update or delete Gramps Place records. Writes: create, update, delete.
action=get lists places (handle empty) or returns one place by handle.
action=create posts a full Place JSON object in data; action=update
PUTs data to /places/; action=delete removes it. Place payload
fields: gramps_id, name, type, longitude, latitude, alt_names,
place_ref_list, enclosed_by, media_list, note_list, change, ... . Use
manage_place with a filter query instead of search when you need raw
object data rather than full-text hits.
Args: action: The operation, "get", "create", "update" or "delete". handle: Place handle; required for get-one, update, delete. data: The Place object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_reportAInspect
List, configure or generate Gramps reports (PDF, text, web...). Writes: run.
action=list returns all available reports (GET /reports/);
action=info describes one report and its options (GET /reports/);
action=run generates a report in the background
(POST /reports//file?options=) returning a task reference;
action=file generates it synchronously (GET /reports//file) and
returns the produced file as base64; action=result downloads a
previously generated file by filename (pass via options or a separate
call: GET /reports//file/processed/). Report options are a
JSON dict documented by each report's options_help (see action=info).
Args: action: "list", "info", "run", "file" or "result". report_id: Report id (e.g. 'descend_report'); required for info, run, file, result. options: Dict of report options (JSON-serialized into the options param). locale: Language code for report output (default server locale). include_help: If true, include the options-help dictionary in list/info. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": reports, task ref, or base64 file}.
Inputs: action (required), locale, options, instance, +2 more.
manage_repositoryAInspect
Create, read, update or delete Gramps Repository records. Writes: create, update, delete.
action=get lists repositories (handle empty) or returns one by handle.
action=create posts a full Repository JSON object in data;
action=update PUTs data to /repositories/; action=delete
removes it. Repository payload fields: gramps_id, type, name, address_list,
url_list, note_list, change, ... . Sources link to a repository through
their reporef_list entry.
Args: action: The operation, "get", "create", "update" or "delete". handle: Repository handle; required for get-one, update, delete. data: The Repository object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_sourceAInspect
Create, read, update or delete Gramps Source records. Writes: create, update, delete.
action=get lists sources (handle empty) or returns one source by
handle. action=create posts a full Source JSON object in data;
action=update PUTs data to /sources/; action=delete removes
it. Source payload fields: gramps_id, title, author, pubinfo, abbrev,
reporef_list, media_list, note_list, change, ... . Citations of a source
are managed with manage_citation.
Args: action: The operation, "get", "create", "update" or "delete". handle: Source handle; required for get-one, update, delete. data: The Source object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_tagAInspect
Create, read, update or delete Gramps Tag records. Writes: create, update, delete.
Tags are lightweight labels attachable to any object. action=get lists
tags (handle empty) or returns one by handle; action=create posts a Tag
JSON object (name required) in data; action=update PUTs data to
/tags/; action=delete removes it. To tag an object, reference the
tag handle in that object's tag_list.
Args: action: The operation, "get", "create", "update" or "delete". handle: Tag handle; required for get-one, update, delete. data: The Tag object for create/update (required for those). query: Optional dict of extra query-string parameters for reads. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data"}.
Inputs: action (required), data, query, handle, +1 more.
manage_transactionAInspect
Apply raw DB transactions, undo history, or bulk create/delete. Writes: all actions.
Low-level database operations that the object endpoints cannot express:
apply -> POST /transactions/ replaying payload (a raw
transaction dict of {add, update, delete} operations).
undo -> POST /transactions/?undo=1 applying the inverse of
payload; pass a recent transaction to revert it.
history -> GET /transactions/history/ (list of past transactions).
history_id -> GET /transactions/history/<transaction_id>.
undo_history -> POST /transactions/history/<transaction_id>/undo.
create_objects -> POST /objects/ with payload = list of object dicts
(validated and added together in one transaction).
delete_objects -> POST /objects/delete/?namespaces= batches an
async delete of whole object types (e.g. 'people,notes').
delete_by_handle -> POST /objects/delete-by-handle/ with namespace (e.g.
'people') and handles (list) to delete specific objects.
params forwards query args for apply/undo: undo, message, force, background.
Prefer the typed manage_* tools for single-record work; raw apply skips
cross-reference maintenance and can corrupt a tree if malformed.
Args: action: "apply", "undo", "history", "history_id", "undo_history", "create_objects", "delete_objects" or "delete_by_handle". payload: Transaction dict (apply/undo) or list of objects (create_objects). params: Optional dict for apply/undo (undo, message, force, background). transaction_id: History transaction id; required for history_id, undo_history. namespace: Object plural namespace (e.g. 'people'); for delete_objects / delete_by_handle. handles: List of handles to delete; for delete_by_handle. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": transaction result or task reference}.
Inputs: action (required), params, handles, payload, +3 more.
manage_treeAInspect
Inspect or administer Gramps Web family trees. Writes: create, update, disable, enable, repair, migrate, verify, config_set.
action=list lists trees (GET /trees/); action=get inspects one tree
(tree_id '-' means the current tree); action=create adds a tree
(data = {"name": , "quota_media", "quota_people", "min_role_ai"});
action=update renames/rescales a tree; action=disable/action=enable
toggle login for a tree; action=repair checks/repairs its database;
action=migrate upgrades its schema; action=verify runs integrity
checks; action=config_get/action=config_set read or write tree
configuration. Admin-only upstream. Note: this API version has no tree
delete endpoint (delete trees via the server CLI).
Args: action: "list", "get", "create", "update", "disable", "enable", "repair", "migrate", "verify", "config_get" or "config_set". tree_id: Tree id; required except for list/create; '-' = current tree. data: Body dict for create/update/config_set (create requires 'name'). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": tree details or configuration}.
Inputs: action (required), data, tree_id, instance.
manage_typeAInspect
List Gramps type vocabularies (custom + default) for all object types. Read-only.
Enumerates the controlled vocabularies used across the schema, e.g. event
types, name types, place types, child reference types, gender types.
action=all merges default and custom types (GET /types/); action=defaults
lists every default vocabulary; action=default returns one vocabulary
(e.g. 'event_types'); action=default_map returns its machine-readable
mapping (standard key -> localized string); action=customs lists every
custom vocabulary; action=custom returns one. Datatypes include:
event_types, event_role_types, name_types, name_origin_types, place_types,
note_types, repository_types, source_attribute_types, source_media_types,
url_types, attribute_types, family_relation_types, child_reference_types,
gender_types (+ person/family/media/event attribute_types on custom).
Values are the strings Gramps objects use in their type fields.
Args: action: "all", "defaults", "default", "default_map", "customs" or "custom". datatype: Vocabulary name (e.g. 'event_types'); required for default, default_map, custom. locale: If true, translate default type names to the server locale. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": vocabulary dict or list}.
Inputs: action, locale, datatype, instance.
manage_userAInspect
Administer Gramps Web users. Writes: create, update, delete, change_password.
action=list lists users (GET /users/); action=get returns one user by
name; action=create POSTs data (full_name, email, password, role and
tree required by the API) to /users/; action=update PUTs data (role,
email, full_name, name_new, tree) to /users/<user_name>/; action=delete
removes the user; action=change_password POSTs with data = {"old_password",
"new_password"}. Requires owner/admin permissions upstream for most actions.
Args: action: "list", "get", "create", "update", "delete" or "change_password". user_name: The user's name; required for get/update/delete/change_password. data: Body dict; required for create/update/change_password. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": user list/object or empty}.
Inputs: action (required), data, instance, user_name.
merge_objectsAInspect
Merge two Gramps objects of the same type into one. Writes: merge.
handle1 (the "phoenix") survives; handle2 (the "titanic") is absorbed
and deleted. Supported obj_type values: person, family, event, place,
source, citation, repository, media, note. Person merges accept
{"family_merger": bool} in data; family merges accept
{"phoenix_father_handle", "phoenix_mother_handle"}. Requires edit+delete
permissions upstream. For duplicate handling of other object types, use
manage_* to probe first, then merge_objects to combine.
Args: obj_type: Object type to merge, e.g. "person" or "family". handle1: Handle that survives the merge (phoenix). handle2: Handle that is absorbed and deleted (titanic). data: Optional merge options dict (person/family specific). instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": {}} on success.
Inputs: handle1 (required), handle2 (required), obj_type (required), data, +1 more.
pingAInspect
Health check. Read-only.
Args: (none)
Returns: dict: {"pong": true, "version": }.
Inputs: no named parameters.
searchAInspect
Full-text (or semantic) search across the Gramps tree. Read-only.
Hits the search index: type-ahead style queries for people, families,
events, places, sources, citations, repositories, media and notes. type
is a comma-delimited allowlist of object types; query is required. Use
manage_<type> with a get/filter instead when you already know the handle
or want raw object data.
Args: query: The search string (required). type: Comma-delimited object types to include, e.g. "person,family,source". page: 1-based result page. pagesize: Results per page (default 20). sort: Comma-delimited sort keys; "change" or "type", '-' prefix for descending (e.g. "-change"). profile: Comma-delimited profile sections: all,self,age,span,events, families,references. strip: If true, drop empty-valued keys from hits. semantic: If true, use the vector/semantic index instead of full text. change: ISO-8601 last-change filter, prefix with '>' or '<'. locale: Language code for localized profile output. instance: Gramps Web base URL from get_instances; default = first.
Returns: dict: {"status", "url", "data": [hits], "total": }.
Inputs: query (required), page, sort, type, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
The manage_* CRUD tools are cleanly separated by entity type, and read-only get_* tools (timeline, relation, living, server info) plus search and merge have distinct purposes. The main friction is that manage_media bundles many sub-actions, manage_export/manage_report both run async jobs and return files, and manage_transaction overlaps with the CRUD tools.
Snake_case verb_noun naming is used throughout (manage_person, get_timeline, merge_objects), making tool selection predictable. Minor deviations exist: bare verbs like ping/search, and manage_import/manage_export/manage_report use 'manage' for action runners rather than entity CRUD.
27 tools is above the comfortable range, but the Gramps Web API is broad and the per-object CRUD tools are parallel rather than redundant. It would benefit from some consolidation, such as splitting media sub-actions into separate tools, so it feels slightly heavy rather than excessive.
The surface covers CRUD for all major Gramps objects plus search, merge, timeline, relationships, living status, DNA, import/export/report, users, trees, bookmarks, types, and metadata. The main gaps are async task polling for exports/reports and a few admin operations like tree deletion.
Maintenance
Related MCP Connectors
Human Lineage MCP server — search and query the public genealogical graph of all humanity
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Remote MCP server to read and edit GanttFather projects: tasks, dates, dependencies, critical path.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to search, retrieve, and create genealogical records in a Gramps Web instance.20 npm4MIT
- AlicenseAqualityAmaintenanceConnect AI assistants to your Gramps Web family tree. Search and edit genealogy records, explore ancestors, descendants, relationships and timelines, and read document scans with vision-capable models. Includes guided research workflows, source citations, read-only mode, and privacy-aware media previews. Install with Docker or a Claude Desktop bundle.23523AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceRead-only MCP server for genealogy data from Family Tree Builder (.ftb) or GEDCOM files, exposing tools for person search, family relationships, and statistical analysis via HTTP or stdio.2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server for Memoo knowledge graph RAG, enabling search, Q&A, graph traversal, and episode management via the Memoo REST API.6 npmApache 2.0