Skip to main content
Glama

Gramps MCP Server

GitHub release Quality gates Security Container security

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.


Related MCP server: Gramps Web MCP

Table of Contents


Why another Gramps MCP server?

Other Gramps MCP servers already exist:

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

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

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 Microsoft.APM -e (or scoop bucket add apm https://github.com/microsoft/scoop-apm; scoop install apm)

    • macOS / Linux: brew install apm

    • Any platform with Python 3.10+: pip install apm-cli

    • Other options: installation docs

  2. Install this package:

    apm install oliverhruby/gramps-mcp

    This single command:

    • writes the uvx gramps-mcp-full stdio 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 (or codex, cursor, ...) to force one harness;

    • deploys the bundled person-research-brief skill into that harness's skills directory (.claude/skills/, .agents/skills/, ...).

  3. Verify:

    apm mcp list        # server registered?

    apm uninstall oliverhruby/gramps-mcp removes 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 . 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

User prompt

Likely tool call(s)

Expected response

"Are we connected and logged in?"

ping → get_instances

Server health and the configured Gramps Web instance(s).

"List all people with birth dates after 1900"

manage_person action="list"

A short list of matching people.

"Show the family tree for person I001"

manage_family action="list" → get_timeline handle="I001"

The person's family and chronological timeline.

"Merge person I002 into I001, keeping I001's data"

merge_objects obj_type="person" handle1="I001" handle2="I002"

Merge confirmation (phoenix survival).

"What is the relationship between person I003 and I020?"

get_relation handle1="I003" handle2="I020"

Degree of kinship plus the path(s) between them.

"Is person I005 likely living?"

get_living handle="I005"

Likely-living verdict or probable birth/death date estimates.

"Analyze DNA matches for person I010"

analyze_dna action="matches" handle="I010"

DNA matches, Y-DNA clade, and parsed segments.

"Upload a media file for person I012"

manage_media action="upload" handle="I012" …

Media object created; thumbnail + OCR available.

"Export the tree as GEDCOM with privacy filters"

manage_export extension="gedcom" options={"privacy": …}

Export file produced and downloadable.

"Import a GEDCOM file (dry-run first)"

manage_import action="import" extension="gedcom" file_path="…"

Dry-run report, then the import result.

"Generate a research report for person I018"

manage_report action="generate" report_id="…"

Report generated and downloadable.

"Apply a raw transaction to update a source"

manage_transaction action="apply" payload="…"

Transaction applied (and undoable later).

"List all users, then disable ciowner"

manage_user action="list" → manage_user action="update" data={…}

User list and the disabled account.

"Create a new tree and configure its base URL"

manage_tree action="create" data={…} → … action="config_set"

New tree created and configured.

"List all default and custom event/place types"

manage_type action="all"

Type vocabularies per object type.

"Get server metadata"

get_server_info

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

Tool

Description

Writes?

ping

Health check.

💡 read

get_instances

List configured Gramps Web instances.

💡 read

manage_person

CRUD Person records (action = get/list/create/update/delete).

✅ create/update/delete

manage_family

CRUD Family records (father/mother/children refs maintained upstream).

✅ create/update/delete

manage_event

CRUD Event records (types from manage_type).

✅ create/update/delete

manage_place

CRUD Place records.

✅ create/update/delete

manage_source

CRUD Source records.

✅ create/update/delete

manage_citation

CRUD Citation records (link to source_handle).

✅ create/update/delete

manage_note

CRUD Note records (holds DNA segment strings, prose, etc.).

✅ create/update/delete

manage_media

CRUD Media + binary upload, file download, thumbnail, OCR, face detection.

✅ create/update/delete/upload

manage_repository

CRUD Repository records.

✅ create/update/delete

manage_tag

CRUD Tag records.

✅ create/update/delete

search

Full-text or semantic search, filterable by object type.

💡 read

merge_objects

Merge two objects of the same type into one.

✅ merge

get_timeline

Chronological event timeline for a person, family, or whole tree.

💡 read

get_relation

Compute a genealogical relationship between two people.

💡 read

get_living

Estimate whether (or until when) a person is alive.

💡 read

analyze_dna

DNA match analysis and raw match-string parsing.

✅ parse only

manage_import

List importers or import a file (Gramps XML, GEDCOM…); dry-run + restore.

✅ file/restore

manage_export

List exporters or produce an export (GEDCOM, Gramps XML…); privacy filters.

✅ run

manage_report

List, configure or generate reports (PDF, text, web…).

✅ run

manage_transaction

Apply raw DB transactions, undo history, or bulk create/delete.

✅ all actions

manage_user

Administer Gramps Web users (create/update/delete/change password).

✅ all actions

manage_tree

Trees: create/update, disable/enable, repair, migrate, verify, config.

✅ all actions

manage_bookmark

Read or edit bookmarks per object namespace.

✅ add/remove

manage_type

List Gramps type vocabularies (custom + default) for all object types.

💡 read

get_server_info

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

Support via PayPal


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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 27 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to search, retrieve, and create genealogical records in a Gramps Web instance.
      20 npm
      4
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Connect 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.
      2
      35
      23
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Read-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.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Memoo knowledge graph RAG, enabling search, Q&A, graph traversal, and episode management via the Memoo REST API.
      6 npm
      Apache 2.0