Health check. Read-only.

Args: (none)

Returns: dict: {"pong": true, "version": }.

List the configured target instances. Read-only.

Args: (none)

Returns: dict: {"instances": [, ...], "scope": "<value of GRAMPS_MCP_INSTANCES, or 'auto-discovery' when unset>"}.

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

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

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

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

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

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

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

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.

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

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

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

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.

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

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

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

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

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

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

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

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/. undo_history -> POST /transactions/history//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}.

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

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

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

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

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