Skip to content
Agentmart
Submit a tool

Gramps MCP Server

MCP server for Gramps genealogy via the Gramps Web API: CRUD, search, merge, timelines, DNA.

Connector by oliverhruby · GitHub account verified by the MCP Registry

IndexedMITLocal (stdio)Remote (HTTP)★ 2
Write a review

Install

Works with Claude Code, VS Code, Codex, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/oliverhruby-gramps-mcp

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Remote endpoint

  • https://ghcr.io/oliverhruby/gramps-mcp:latest Remote (HTTP)

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

MCP server for Gramps genealogy via the Gramps Web API: CRUD, search, merge, timelines, DNA.

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools
8 read · 9 write · 10 delete
Secrets
2 (API keys, tokens or passwords)
Install scripts
None found
Runs as
Python package

Tools by what they do 27

Read from the source code; the running server may list different tools.

Read 8 · Look things up without changing anything.

  • analyze_dna
  • get_instances
  • get_living
  • get_relation
  • get_server_info
  • get_timeline
  • ping
  • search

Write 9 · Create, change, send or run things.

  • manage_bookmark
  • manage_export
  • manage_import
  • manage_media
  • manage_report
  • manage_tree
  • manage_type
  • manage_user
  • merge_objects

Delete 10 · Delete, drop, revoke or wipe things.

  • manage_citation
  • manage_event
  • manage_family
  • manage_note
  • manage_person
  • manage_place
  • manage_repository
  • manage_source
  • manage_tag
  • manage_transaction

Secrets and settings it asks for

Secrets: values you paste in that let it act as you.

  • GRAMPS_MCP_PASSWORD
  • GRAMPS_MCP_USERNAME

Other settings (environment variables or headers).

  • GRAMPS_MCP_INSTANCES

Network hosts it talks to 4

  • ghcr.io · found in remote endpoint, install command, code
  • github.com · found in code
  • glama.ai · found in code
  • tdqs.dev · found in code

Files it touches

  • Any path the agent passes to its tools

Tools (27)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

  • analyze_dna

    DNA match analysis and raw match-string parsing. Writes: parse only. Actions: matches -> GET /people/<handle>/dna/matches; per-match relationship, segments, common-ancestor profiles and citation-linked notes. ydna -> GET /people/<handle>/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. A…

  • get_instances

    List the configured target instances. Read-only. Args: (none) Returns: dict: {"instances": [<base url>, ...], "scope": "<value of GRAMPS_MCP_INSTANCES, or 'auto-discovery' when unset>"}.

  • get_living

    Estimate whether (or until when) a person is alive. Read-only. `mode=status` returns {"living": bool} from /living/<handle>; `mode=dates` returns probable birth/death date estimates plus an explanation from /living/<handle>/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 g…

  • get_relation

    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/<h1>/<h2> or /relations/<h1>/<h2>/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). …

  • get_server_info

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

  • get_timeline

    Chronological event timeline for a person, family, or the whole tree. Read-only. `kind=person` -> /people/<handle>/timeline; `kind=family` -> /families/<handle>/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 pe…

  • manage_bookmark

    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/<ns>); `action=add` bookmarks a handle (PUT /bookmarks/<ns>/<handle>, idempotent); `action=remove` unbookmarks it (DELETE). Adding validates that the object exists. Args: namespace: Bookmark namespace (one of the nine object plurals). action: …

  • manage_citation

    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/<handle>; `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". hand…

  • manage_event

    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/<handle>; `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; require…

  • manage_export

    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/<extension>); `action=run` starts an asynchronous export (POST /exporters/<extension>/file) and returns a task reference (poll with manage_transaction or re-call to fetch); `action=file` runs a synchronous export (GET /exporters/<extension>/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/Full…

  • manage_family

    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/<handle>; `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: acti…

  • manage_import

    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/<extension>); `action=file` uploads `file_path` to /importers/<extension>/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/<extension>/file/restore (replaces all content; requires batch delete permission). Use `dry_run=true` on file/restore to preview counts and changes withou…

  • manage_media

    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/<handle>/file; returns base64 bytes. thumbnail -> GET /media/<handle>/thumbnail/<size>; returns …

  • manage_note

    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/<handle>; `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-o…

  • manage_person

    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/<handle>; `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, ...). Arg…

Show 12 more tools
  • manage_place

    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/<handle>; `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…

  • manage_report

    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/<id>); `action=run` generates a report in the background (POST /reports/<id>/file?options=<json>) returning a task reference; `action=file` generates it synchronously (GET /reports/<id>/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/<id>/file/processed/<filename>). Report op…

  • manage_repository

    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/<handle>; `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, …

  • manage_source

    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/<handle>; `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, upda…

  • manage_tag

    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/<handle>; `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 (…

  • manage_transaction

    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…

  • manage_tree

    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": <required>, "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…

  • manage_type

    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,…

  • manage_user

    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 "chang…

  • merge_objects

    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…

  • ping

    Health check. Read-only. Args: (none) Returns: dict: {"pong": true, "version": <server version>}.

  • search

    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: Co…

Signals

Stars
2
Forks
0
Open issues
0
Weekly downloads
123
Last commit
Oct 23, 2026 (5 days ago)
Last release
Oct 19, 2026 (9 days ago)
Last package publish
Oct 19, 2026 (9 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name
io.github.oliverhruby/gramps-mcp
Version
0.2.1
Auth
Auth not stated, API key
Packages
pypi gramps-mcp-full
License
MIT
Repository
github.com/oliverhruby/gramps-mcp
Website
github.com/oliverhruby/gramps-mcp
First seen
Oct 24, 2026
Last checked
Oct 24, 2026
Source
Official MCP Registrygithub-graphql

More from oliverhruby

Cite this page

Gramps MCP Server. Agent Mart. https://agentmart.dev/connectors/oliverhruby-gramps-mcp (last updated 2026-10-24)