Gramps MCP MCP Server

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

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

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 gap tolerated (>= 1). instance: Gramps Web base URL from get_instances; default = first. Returns: dict: {"status", "url", "data": <living verdict or date estimates>}.

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). instance: Gramps Web base URL from get_instances; default = first. Returns: dict: {"status", "url", "data": relationship(s)}.

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

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

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: "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}.

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

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; 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"}.

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

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: 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"}.

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

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 base64 image; pass {"square": true} in `query`. ocr -> GET /media/<handle>/ocr; returns OCR text. face_detection -> GET /media/<handle>/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.

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

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, ...). 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": <http status>, "url": <api url>, "data": <object(s) | transaction>}.

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", "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"}.

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

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, 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"}.

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, 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"}.

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 (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"}.

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=<csv> 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", "d…

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

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

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

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.

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

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": <match count>}.