Gramps Evidence
PYPI · GRAMPS-EVIDENCE-MCP
Read/write a self-hosted Gramps Web family tree where every fact carries a citation.
Available components
Last scanned (13 hours ago)
Scores higher than 76% of PyPI servers
Category Health and Science
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score → Why this is hard to score →
Supply Chain Security50
- Malware scan not yet available for this package.Unverified
- No known CVEs affecting this package version or its production dependencies.Pass
- Runs hatchling.build at install time, a recognised build step with no custom scripting around it. View diagnostics → Pass
- 1 of 34 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency100
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Cryptographically verified build provenance (signed, bound to ianderso/gramps-evidence-mcp). View diagnostics → Pass
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 42 days ago).Pass
- Publishes a security disclosure policy (SECURITY.md).Pass
Schema Quality & AI Usability67
- AI-judged instruction clarity (excellent).Pass
- Context-footprint check failed: tool/resource definitions use about 17270 tokens (~178/item across 97 items; 97 tools + 0 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management100
- No destabilizing schema changes in the last 30 days.Pass
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
Tool Safety95
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- 4 of 5 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "consolidated_timeline" implies "merge" and declares readOnlyHint instead, contradicting what its own name says it does. See how to fix → Partial
- An AI judge read all 98 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a current MCP spec version (2026-07-28).Pass
Checks we ran (15)
- Known CVEs
- Install scripts
- Dependency health
- Source repository
- Provenance
- License
- Maintenance
- Security disclosure
- Schema quality
- Stability
- Tool coverage
- Injection markers
- Destructive annotations
- Judged manipulation
- MCP protocol
Checks we could not complete (1)
These are gaps on our side, not findings about this package. We only credit what we can confirm, so a category made up entirely of them scores 0.
- Malware scan in Supply Chain SecurityMalware scan not yet available for this package.
Does not apply to this package (2)
- Endpoint SecurityScored on hosted endpoints only. A package has no live endpoint of its own for us to probe.
- Transport & ReachabilityScored on hosted endpoints only. A package has no live endpoint of its own for us to probe.
The score does not measure everything. What the score does not measure →
Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 21 Nov 26 −15
- Malware scan: pass → unverified ▼ security
- 20 Nov 26 +16
- Malware scan: unverified → pass ▲ security
- Stability: 0.97 → pass security
- 19 Nov 26 −1
- Stability: pass → 0.97 functional
- 13 Nov 26 +1
- Stability: 0.97 → pass security
- 11 Nov 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 90 to 93. That category is still filling its 30-day observation window: 27 days of observed history at the previous scan, 28 at this one. The score rises as the window fills, whether or not the server changes.
- 9 Nov 26 −14
- Malware scan: pass → unverified ▼ security
- 7 Nov 26 +15
- Malware scan: unverified → pass ▲ security
- 6 Nov 26 −2
- Stability: fail → 0.77 functional
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 21 Nov 2026 · Analysed pypi/gramps-evidence-mcp@2.3.0
Provenance Verified
A signed build attestation was found and verified, binding this exact artifact to the source repository it claims to come from.
| Result | Verified |
|---|---|
| Ecosystem | pypi |
| Reason | Verified |
| Discovered via | Registry attestation endpoint |
| Source repo | ianderso/gramps-evidence-mcp |
| Certificate issuer | https://token.actions.githubusercontent.com |
| Certificate SAN | https://github.com/ianderso/gramps-evidence-mcp/.github/workflows/release.yml@refs/tags/v2.3.0 |
| Rekor log index | 3177997228 |
| Predicate type | PyPI publish attestation https://docs.pypi.org/attestations/publish/v1 |
| Subject digest | sha256:5b9f5fa87ccad117e30652c1a797c78e9b931b3bbf05cb7e5f4e4b4dff5b13c8 |
Background: How many MCP packages publish verified provenance →
Install scripts 1 script
| Hook | Tier | Command |
|---|---|---|
| build_backend | Known build tool | hatchling.build |
Background: Why install scripts are a supply-chain risk →
Dependencies 34 packages
| Packages resolved | 34 |
|---|---|
| No linked repository | 1 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
get_repository ~54
Get a repository: name, type, URLs, address count, and (if available) the number of sources it holds.
| Name | Type | Req | Description |
|---|---|---|---|
| repository | string | yes | Repository handle or gramps_id, e.g. 'R0001'. |
No output schema declared.
No examples provided.
get_researcher ~50
Read the researcher details recorded for this tree. These are embedded in every export, so they travel with any GEDCOM or Gramps XML you hand to someone else. Worth checking before sharing one.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
get_source ~70
Get a source: title, author, publication info, abbreviation, linked repositories, media/note counts, attributes, and citation count. Use to inspect a source before citing through it or editing it.
| Name | Type | Req | Description |
|---|---|---|---|
| source | string | yes | Source handle or gramps_id, e.g. 'S0001'. |
No output schema declared.
No examples provided.
get_timeline ~221
Build a chronological timeline of someone's life events. Each entry carries their age at the time, how many citations support the event, and the strongest confidence among them — so a timeline doubles as a readable audit of where the evidence thins out. `uncited_count` says how many events on it rest on nothing.
| Name | Type | Req | Description |
|---|---|---|---|
| ancestors | – | – | Generations (1-5) of ancestors whose events to fold in. Omit this and offspring for the person's own events only. Given either, the server adds at least one generation each way; each event's person.r… |
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| limit | integer | – | Maximum events to return. |
| object_type | string | – | Either 'person' or 'family'. |
| offspring | – | – | Generations (1-5) of descendants whose events to fold in. |
| target | string | yes | Handle or gramps_id of the person or family. |
No output schema declared.
No examples provided.
get_transaction ~51
Read one transaction in full, including the objects it changed. list_transactions summarises; this shows what actually moved. Read it before undoing anything.
| Name | Type | Req | Description |
|---|---|---|---|
| transaction_id | integer | yes | Id from list_transactions. |
No output schema declared.
No examples provided.
get_ydna ~145
Report a person's Y-DNA haplogroup, from broadest clade to terminal. Y-DNA follows the direct paternal line only, so it speaks to one thread of a tree and is silent on every other. A shared terminal clade indicates a common paternal ancestor, usually far further back than any record reaches — it corroborates a surname line rather than proving a named link. `has_data` is false when the person has no Y-DNA recorded, which is the normal case.
| Name | Type | Req | Description |
|---|---|---|---|
| include_raw | boolean | – | Include the raw SNP data string. |
| person | string | yes | Handle or gramps_id of the tested person. |
No output schema declared.
No examples provided.
link_repositories ~130
Link many sources to their repositories in one call -- a sweep. Each row is link_repository: its own write and transaction, so a failed row does not stop the rest. Each row reports linked, already_linked, missing or error.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| items | array | yes | Rows of {source, repository, call_number?, media_type?}. |
No output schema declared.
No examples provided.
link_repository ~188
Link an existing source to an existing repository that holds it. Adds a repository reference (with an optional call number) to the source. Both objects must already exist. Duplicate links to the same repository are skipped.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| call_number | – | – | Call number / reference within the repository. |
| media_type | string | – | Medium of the source at the repository, e.g. 'Book', 'Film', 'Electronic', 'Unknown'. |
| repository | string | yes | Repository handle or gramps_id (e.g. 'R0001'). |
| source | string | yes | Source handle or gramps_id (e.g. 'S0001'). |
No output schema declared.
No examples provided.
list_custom_filters ~63
List the custom filters already saved on this instance. A saved filter can be reused by name from `query_objects` and the timelines, so a complicated selection is defined once.
| Name | Type | Req | Description |
|---|---|---|---|
| namespace | string | – | Restrict to one namespace. Omit for all. |
No output schema declared.
No examples provided.
list_event_types ~63
List the event type names this tree uses, with their stored integers. Useful before a `query_records` filter, and as a check on itself: an unexpected type name in the list is usually a typo that Gramps silently accepted as a new custom type.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
list_filter_rules ~93
List the filter rules Gramps offers in a namespace. This is the vocabulary that `query_records` and GrampsQL cannot reach: "is a descendant of", "has a common ancestor with", "matches another filter". Read it before building a custom filter with create_filter.
| Name | Type | Req | Description |
|---|---|---|---|
| namespace | string | – | Plural namespace: people, families, events, places, sources, citations, repositories, media, notes. |
No output schema declared.
No examples provided.
list_jobs ~72
List recent background jobs for this tree, newest first: undo, verify, reindex, report. Use when you have lost a task_id, or to see whether anything is still running before starting a write session. Research tasks are list_research_tasks.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | Maximum jobs to return. |
No output schema declared.
No examples provided.
list_object_types ~71
The tree's type vocabularies: Gramps' standard names and its own custom ones. The write tools take any of these, in any case. A name in neither is refused unless allow_new_type asks for a NEW custom type, which then stays in the tree's vocabulary for good.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
list_reports ~85
List the reports this Gramps instance can generate. Gramps ships a full report engine — Ahnentafel, descendant reports, family group sheets, kinship, fan and relationship charts, statistics, and an end-of-line report that lists exactly where research stops. Each entry names the option keys it accepts; read the defaults with get_report_options before overriding any.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
list_research_tasks ~160
List the research tasks in Gramps Web's Tasks view: title, status, priority, tags, attributes and description. Ordered as the view orders them: Open, In Progress, Blocked, Done. Not background jobs (list_jobs). A private task is a redacted stub.
| Name | Type | Req | Description |
|---|---|---|---|
| attributes | – | – | Only tasks with these attribute values, ignoring case; an empty value matches any value, e.g. {'Request-Custodian': ''}. |
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| status | – | – | Only these states, e.g. ['Open', 'In Progress']. |
| tag | – | – | Only tasks also carrying this tag. |
No output schema declared.
No examples provided.
list_tags ~41
List all tags in the tree with their handle, name, and color. Use to see what labels already exist before tagging (tag_object matches by exact name).
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
list_transactions ~73
Recent writes to the tree: what changed, when, by which user. Each entry's transaction_id is what undo_transaction takes. Useful for "what did that bulk pass actually do?" and for finding the transaction to reverse when it did the wrong thing.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | How many, newest first. |
No output schema declared.
No examples provided.
list_unsourced_facts ~125
Audit: list events that lack a citation or are tagged UNSOURCED. This is the core quality query for a fully-cited tree -- run it to find facts that still need a source. Returns each offending event with its person, type, date, and the reason ('no-citation' or 'tagged-unsourced').
| Name | Type | Req | Description |
|---|---|---|---|
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| person | – | – | Optional: restrict to one person (handle/gramps_id). |
No output schema declared.
No examples provided.
merge_objects ~351
Merge two objects that are the same thing. Dry-run by default. This uses Gramps' own server-side merge: every reference to `drop` is re-pointed at `keep` and the subordinate lists are unioned, in one transaction. Do NOT do this by hand: a manual merge that misses one of the lists the dropped object carries loses what was on it. Before merging, be sure they really are one thing. Two records OF the same event are two documents: an index entry and the register page it indexes stay separate, and merging them would turn two independent citations into one, silently weakening every fact that rested on both. Conversely, the same census page entered once per household member IS one document, and leaving the duplicates makes single-sourced facts look corroborated. Reversible: the merge is one transaction, so list_transactions + undo_transaction can back it out.
| Name | Type | Req | Description |
|---|---|---|---|
| drop | string | yes | Handle or gramps_id of the object absorbed into it. |
| dry_run | boolean | – | True (default) reports what would move without changing anything. Set False to apply. |
| enclosures | string | – | Places only: the survivor otherwise gets both places' parents. 'auto' drops an undated parent that encloses another (a state beside its county) and refuses if two unrelated undated parents remain; or… |
| keep | string | yes | Handle or gramps_id of the object that SURVIVES. |
| object_type | string | yes | person, family, event, place, source, citation, repository, media, or note. |
No output schema declared.
No examples provided.
move_child ~190
Move a child to another family with the link's citations and notes, placed in birth order. Detaching and re-adding loses both. The new family is written first: a failure leaves the child in both, never in neither.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| child | string | yes | The child's handle or gramps_id. |
| frel | – | – | New relationship to the father, e.g. 'Stepchild'. Omit to keep. |
| from_family | string | yes | The family the child is in now. |
| mrel | – | – | New relationship to the mother. Omit to keep. |
| to_family | string | yes | The family to move them to. |
No output schema declared.
No examples provided.
ocr_media ~536
Read a document image with the reader that suits it; doc_type and lang choose. print: text the media or its sources already carry, else Tesseract. hand: an English hand returns the image for you to transcribe as the result instructs; German goes to Transkribus only, never a vision read; Norwegian and others to Transkribus, with the image to check. table: FamilySearch's index (get_records_on_image). volume: full-text search first. Transkribus costs credits: within the monthly budget, or with spend_credits. The transcript is never the evidence; the citation stays on the image.
| Name | Type | Req | Description |
|---|---|---|---|
| doc_type | – | – | What the document is. 'print': typeset or typed. 'hand': one handwritten document -- will, deed, letter, register entry. 'table': a census page or other ruled form. 'volume': a page of a register or… |
| engine | – | – | 'auto' routes by doc_type and lang. Or one reader: 'existing' (text the media or its sources already carry), 'tesseract', 'vision' (the image, for you to read; refused for German handwriting), 'trans… |
| lang | string | – | The document's language, as a Tesseract code: 'eng', 'deu', 'nor', 'swe', 'dan', 'lat'; 'eng+deu' for several. Chooses the handwriting route and Tesseract's model. |
| media | string | yes | Media handle or gramps_id. |
| page | integer | – | Page of a PDF, from 1. |
| region | – | – | Return only [x1, y1, x2, y2] of the page, in percent of width and height, at full detail: to read small or faint writing. [0, 50, 100, 100] is the bottom half. |
| second_witness | boolean | – | With a vision read, also run Transkribus and compare -- for a document that will carry a proof argument. Costs credits. |
| spend_credits | boolean | – | Consent to Transkribus credits (about 0.5, EUR 0.12, a page) for this call, past the configured monthly page budget. Only when the user agreed. |
| store | boolean | – | Keep a machine reading on the media object as a Transcript note headed with its engine, model and date, plus Transkribus' PAGE XML. A vision read is yours to store, with add_note. |
No output schema declared.
No examples provided.
parse_dna_segments ~170
Parse pasted shared-segment data into structured segments and totals. Use this to check what a match file actually contains before recording it. Returns each segment plus the total and largest-segment centiMorgans. If nothing parses, `parsed` is false and the reason is given. That distinction matters: the server answers unreadable input with zero segments and a success status, which would otherwise read as "this person shares no DNA" rather than "I could not read that".
| Name | Type | Req | Description |
|---|---|---|---|
| data | string | yes | Raw shared-segment data, as a testing company exports it: rows of chromosome, start, stop, centiMorgans, SNPs, separated by commas or tabs, with an optional side of M, P or U. A header row is tolerat… |
No output schema declared.
No examples provided.
query_objects ~633
Query any collection with a server-side filter. The workhorse for audits. Use this instead of fetching a collection and filtering it yourself: whole-collection pulls are slow on any real tree, and the filter runs in the database. Typical audit questions it answers directly: * uncited high-confidence claims: citations where `confidence >= 3 AND page = ""` * documents with no image: sources where `media_list.length = 0` * anonymous media: media where `desc = ""` * a URL anywhere: `urls.any.path ~ "blm.gov"`; a list is searched through its items, never with `~` on the list itself To ask "what cites this source?" use get_backlinks -- a source has no citation_list, because citations point at IT, and reading citation_list on a source reports zero for every source in the tree. Private records and living people come back as redacted stubs.
| Name | Type | Req | Description |
|---|---|---|---|
| gql | – | – | GrampsQL filter, applied server-side over the RAW object JSON. Single '=' for equality (NOT '=='), '~' for substring, '<list>.length' for sizes, combined with AND/OR. Examples: 'confidence >= 3 AND p… |
| gramps_ids | – | – | Fetch these specific gramps_ids (e.g. ['S0001','S0002']). |
| handles | – | – | Fetch these specific handles in one request. |
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| keys | – | – | Comma-separated fields to return, e.g. 'gramps_id,title,media_list'. Strongly recommended -- whole objects are large. NEVER build a write payload from a keys= result: writes replace the whole record. |
| limit | integer | – | Max rows to return. |
| object_type | string | yes | One of: person, family, event, place, source, citation, repository, media, note, tag. |
| page | integer | – | Page of results, 1-based. |
| sort | – | – | Sort key; prefix '-' for descending (e.g. '-change'). |
No output schema declared.
No examples provided.
query_records ~523
Query any collection server-side, with columns, filters and sorting. More capable than `query_objects` and the tool to reach for on an audit. It reads indexed columns, reaches arbitrary paths inside the stored object, and follows relationships — so "families where the mother died before the father" or "events whose place is in Ohio" are single queries. **It is the only way to filter events by type.** GrampsQL cannot: the word is shadowed, so `type = "Birth"` silently matches nothing. Pass `event_type` here instead. Returns rows plus a total count and a `next_after` cursor. Private records, living people and families with a living parent come back as redacted stubs.
| Name | Type | Req | Description |
|---|---|---|---|
| after | string | – | Cursor from a previous response's next_after, for paging past the first page. |
| event_type | string | – | Events only. Filter by type name such as 'Birth' or 'Census'. Translated to the integer the tree stores, which is the only way event type is filterable at all. |
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| limit | integer | – | Maximum rows (1-500). |
| object_type | string | yes | Collection to query: person, family, event, place, source, citation, repository, media, note, or tag. |
| order_by | – | – | Sort keys, each {"column": ..., "direction": "asc" or "desc"}. json_path is not usable here. |
| select | – | – | Columns to return. A plain column name, or {"json_path": [...], "as": "label"} to reach into the stored object. A path may cross a relationship: person->birth/death, family->father/mother, event->pla… |
| where | – | – | Conditions combined with AND. Each is {"column": <name or json_path>, "op": <op>, "value": ...}. Operators: eq, ne, lt, lte, gt, gte, like, regex, contains, in. Use "value_column" instead of "value"… |
| where_expr | – | – | An expression instead of `where`, e.g. "surname == 'Smith'". |
No output schema declared.
No examples provided.
reindex_search ~91
Rebuild the full-text index behind Gramps Web's search box. The server updates the index in the background after each write. Rebuild it after a large import, or when search misses something the tree holds. Returns a task_id to poll with get_job.
| Name | Type | Req | Description |
|---|---|---|---|
| full | boolean | – | Rebuild from scratch rather than updating incrementally. Slower, and the right choice after a large import. |
No output schema declared.
No examples provided.
run_report ~170
Generate a report and return the file it produced. Living people and private records are left out (living_people 0, incl_private false) unless you pass those options or include_private; Gramps' own default includes both. Usually runs in the background, returning a task_id to poll with get_job.
| Name | Type | Req | Description |
|---|---|---|---|
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| locale | string | – | Language code for the report output. |
| options | – | – | Overrides for the report's defaults, merged over them. Common keys: 'pid' (the central person's gramps_id), 'maxgen', 'off' (output format), 'living_people'. |
| report_id | string | yes | Report id, from list_reports. |
No output schema declared.
No examples provided.
search_people ~142
Search people by name substring and optional birth-year range. Bulk output: probably-living people (born < 110 years ago with no recorded death) and records marked private are returned as redacted stubs (ids only) unless include_private is set. Fetch a specific person by id with get_person if you need their detail.
| Name | Type | Req | Description |
|---|---|---|---|
| birth_year_max | – | – | Latest birth year. |
| birth_year_min | – | – | Earliest birth year. |
| include_private | boolean | – | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |
| name | string | yes | Name substring to match (case-insensitive). |
No output schema declared.
No examples provided.
set_family_parent ~110
Set, replace or remove the father or mother of an existing family -- the wife a record names -- keeping both sides of every link, children and all.
| Name | Type | Req | Description |
|---|---|---|---|
| family | string | yes | Family handle or gramps_id (e.g. 'F0001'). |
| person | – | – | The parent's handle or gramps_id. Omit to remove the parent. |
| replace | boolean | – | Replace a different parent the role already has; refused otherwise. |
| role | string | yes | Which parent to set. |
No output schema declared.
No examples provided.
set_private ~109
Set (or clear) the Gramps private flag on an object. Private records are withheld from bulk output (queries, searches, tree walks, timelines, reports) unless a call passes include_private.
| Name | Type | Req | Description |
|---|---|---|---|
| object_type | string | yes | Type of the object: 'person', 'family', 'event', 'source', etc. |
| private | boolean | – | True to mark private (default), False to un-mark. |
| target | string | yes | Handle or gramps_id of the object. |
No output schema declared.
No examples provided.
tag_object ~190
Attach a named Tag to an object, creating the Tag if it doesn't exist yet. Tags are lightweight cross-cutting labels ('Verified', 'Needs review', 'DNA-confirmed'). Matching is by exact name; an existing tag is reused.
| Name | Type | Req | Description |
|---|---|---|---|
| color | – | – | Optional hex color for a newly-created tag, e.g. '#FF8800'. Defaults to '#4444FF'. Ignored if the tag already exists. |
| object_type | string | yes | Type of the object to tag: 'person', 'family', 'event', 'source', 'citation', 'place', 'repository', 'media', 'note'. |
| tag | string | yes | Tag name (found-or-created by exact match), e.g. 'Verified'. To REMOVE a tag: detach_object(child_kind='tag', child=<tag name>). |
| target | string | yes | Handle or gramps_id of the object to tag. |
No output schema declared.
No examples provided.
uncite ~242
Detach a citation from an object, deleting it if it is left orphaned. Detaching without deleting is how orphan citations accumulate: the fact the citation supported is gone, but the citation sits in the database still looking like evidence of something. Use this when a citation was attached to the wrong fact, or when a superseded bucket citation is replaced by the real record.
| Name | Type | Req | Description |
|---|---|---|---|
| carry_to | – | – | Citation (handle or gramps_id) to receive the notes and images only this citation holds, so it can be deleted without losing them. |
| citation | string | yes | Citation handle or gramps_id to remove. |
| delete_if_orphan | boolean | – | Delete the citation if nothing else references it after detaching. Leave True unless you are keeping it deliberately. A citation that holds the only link to a note or image is kept unless carry_to is… |
| name | – | – | With object_type='name' (ref is the person): which of the person's names to detach the citation from. |
| object_type | string | yes | Type of the object to detach from. |
| ref | string | yes | Handle or gramps_id of that object. |
No output schema declared.
No examples provided.
undo_transaction ~136
Undo a past transaction, after checking whether it can be undone cleanly. A conflict means an object was edited again after this transaction; undoing anyway throws that later edit away. The conflict check is free and runs first, so the default tells you what you are dealing with before anything changes.
| Name | Type | Req | Description |
|---|---|---|---|
| dry_run | boolean | – | True (default) only checks whether the undo is clean. Set False to actually undo. |
| force | boolean | – | Undo even when there are conflicts. This DISCARDS edits made to those objects after the transaction. Use deliberately. |
| transaction_id | integer | yes | From list_transactions. |
No output schema declared.
No examples provided.
update_alternate_name ~256
Correct, retype or remove one alternate name, in place. Edited in place, the name keeps its citations. The primary name is update_person(name=...); a new name is add_alternate_name.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| given | – | – | New given name(s). Omit to keep. |
| match | – | yes | Which alternate name, e.g. {'surname': 'Calloway', 'type': 'Also Known As'}. get_person lists them with their index. |
| name_prefix | – | – | New surname prefix. |
| name_suffix | – | – | New suffix. |
| name_type | – | – | New type, e.g. 'Married Name' for a name filed as 'Also Known As'. |
| nickname | – | – | New nickname. |
| person | string | yes | Person handle or gramps_id. |
| remove | boolean | – | Remove the name. Refused while it carries citations or notes; of identical duplicates, one is removed. |
| surname | – | – | New surname. Omit to keep. |
No output schema declared.
No examples provided.
update_attribute ~167
Set or remove ONE attribute on an object in place, keeping its citations, notes and privacy.
| Name | Type | Req | Description |
|---|---|---|---|
| match | – | – | Case-insensitive part of the current value, to pick one of several attributes of this name. Matching none, or several that differ, changes nothing and lists them. |
| name | string | yes | Name (type) of the attribute to change, e.g. 'Occupation'. |
| object_type | string | yes | Type of the object: 'person', 'event', 'family', 'media', 'source', 'citation'. |
| remove | boolean | – | Remove the attribute. Its citations stay in the tree and are named. |
| target | string | yes | Handle or gramps_id of the object. |
| value | – | – | Its new value. Omit when removing it. |
No output schema declared.
No examples provided.
update_child_ref ~207
Change a child's relationship to the father or mother -- a stepson held as a birth child -- in place. The child keeps the link's citations, notes and its place in the birth order, which detaching and re-adding the child loses.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| child | string | yes | The child's person handle or gramps_id. |
| family | string | yes | Family handle or gramps_id (e.g. 'F0001'). |
| frel | – | – | Relationship to the father: 'Birth', 'Adopted', 'Stepchild', 'Foster', 'Sponsored', 'Unknown', 'None'. Omit to keep. |
| mrel | – | – | Relationship to the mother, the same values. Omit to keep. |
No output schema declared.
No examples provided.
update_citation ~284
Edit a citation's locator, confidence, date, or the source it points at. A page-less citation on a long document is not a locator, and a confidence is a per-instance judgement, not a property of the source class. IMPORTANT: a citation carries ONE confidence, and it belongs to ONE claim. Every fact attached to this citation shares whatever you set here. If the same page supports a second, different claim (a census page proving both "this child appears here" and "these are her parents"), make a SECOND citation on the same source and page -- do not re-grade this one.
| Name | Type | Req | Description |
|---|---|---|---|
| citation | string | yes | Citation handle or gramps_id (e.g. 'C0001'). |
| confidence | – | – | Re-grade this citation. very_high is for an original record read from an image, and nothing else. |
| date | – | – | Date recorded/accessed. |
| page | – | – | The locator: WHERE in the source this fact appears ('p. 45, entry 12', 'ED 12, sheet 4A, dwelling 57', memorial number). Omit to leave unchanged. |
| source | – | – | RE-POINT this citation at a different source (handle or gramps_id). Use when a fact was cited to a compiled bucket but the real record is in the tree, or when a container source has been split. |
No output schema declared.
No examples provided.
update_citations ~93
Re-write many citations' pages or confidences in one call -- a sweep. Each row is update_citation: its own write and transaction. A row whose live page no longer starts with expect_page_prefix is reported as drifted, not overwritten. Rows report applied, unchanged, drifted, missing or error.
| Name | Type | Req | Description |
|---|---|---|---|
| items | array | yes | Rows of {citation, page?, confidence?, expect_page_prefix?}. |
No output schema declared.
No examples provided.
update_event ~370
Edit an existing event in place: its type, date, place or description. Only what you pass changes. The event keeps its id, citations, notes, media and every person sharing it, so correct a wrong type or an unsupported place here rather than replacing the event. Citations: cite_event.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept an event_type the tree does not have yet, creating it as a custom type. Only for a deliberate new type, never a typo. |
| clear_date | boolean | – | Remove the event's date. |
| clear_place | boolean | – | Remove the event's place, e.g. one no source states. An empty place string is refused rather than read as this. |
| date | – | – | New date, Gramps style: '1899', '12 JAN 1899', 'ABT 1900', 'BEF 1950'; 'BET 1898 AND 1901' happened once within the range; 'FROM 4 MAY 1864 TO 16 SEP 1864' lasted the whole span; 'FROM 1880' or 'TO 1… |
| description | – | – | New free-text description. Omit to leave unchanged. |
| event | string | yes | Event handle or gramps_id (e.g. 'E0007'). |
| event_type | – | – | New event type, e.g. 'Census', 'Visit'. Must already be a standard or custom type in the tree (list_object_types) unless allow_new_type is set. Omit to leave unchanged. |
| place | – | – | New place: existing handle/gramps_id, exact title, or exact unique name — created only if nothing matches. Omit to leave unchanged. |
No output schema declared.
No examples provided.
update_event_ref ~174
Change a person's reference to a shared event in place: its role, or attributes such as 'As enumerated' or 'Age'.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| attributes | – | – | Attribute name to new value; null removes it. The first of a name is set in place, keeping its citations; a name the reference lacks is added. |
| event | string | yes | Handle or gramps_id of the event they reference. |
| person | string | yes | Handle or gramps_id of the person. |
| role | – | – | New role, e.g. 'Witness'. Omit to keep. |
No output schema declared.
No examples provided.
update_media ~102
Edit a media object's description, date, or path.
| Name | Type | Req | Description |
|---|---|---|---|
| date | – | – | Date of the document/photo. |
| description | – | – | What this document IS ('1900 US census, Cedar Flat, Brannock Co., Ohio, ED 12 sheet 4A'). Files are stored under checksum names, so without this the media list says nothing about the document. |
| media | string | yes | Media handle or gramps_id. |
| path | – | – | Stored path/filename. |
No output schema declared.
No examples provided.
update_object_fields ~208
Set scalar fields on any object -- the escape hatch for places, notes, repositories and the rest. Only scalar fields are settable. Structural lists (citation_list, event_ref_list, media_list, ...) are refused on purpose: replacing one wholesale is exactly how references get silently dropped. Each has its own tool -- cite_object, detach_object, tag_object, attach_media.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| fields | object | yes | Scalar fields to set, e.g. {'name': 'Cedar Flat, Brannock, Ohio, USA'} on a place, or {'text': '...'} on a note. |
| object_type | string | yes | Type of object to edit. |
| ref | string | yes | Handle or gramps_id. |
No output schema declared.
No examples provided.
update_person ~234
Edit a person's gender, primary name, or privacy flag. Replacing the primary name preserves the old one as an 'Also Known As': a name in the tree came from some record, and dropping it loses the link to whatever document used it. To add a name without replacing the primary one, use add_alternate_name.
| Name | Type | Req | Description |
|---|---|---|---|
| gender | – | – | female, male, or unknown. |
| keep_old_as_alternate | boolean | – | False only to fix a data-entry error -- a name split wrongly between given and surname, a typo no record contains -- where keeping the old form would invent a variant. The name is then corrected in p… |
| name | – | – | New PRIMARY name. The current primary name is kept as an alternate rather than discarded, unless keep_old_as_alternate is False. |
| person | string | yes | Person handle or gramps_id (e.g. 'I0001'). |
| private | – | – | Gramps private flag. |
| reason | – | – | Why the old form is not kept. Required with keep_old_as_alternate=False. |
No output schema declared.
No examples provided.
update_place ~414
Edit a place's type, parent enclosure, name, title, or coordinates. This is the tool update_object_fields deliberately refuses to be: place_type and the enclosure are structural, so they get guard rails here -- the parent must already exist, setting it cannot create an enclosure cycle, and a place holding several dated enclosures (a territory-to-state succession) is refused rather than silently flattened. Aim for every place typed, every non-country place parented, and street addresses on events rather than in the place tree.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| code | – | – | Place code (postal etc.). |
| latitude | – | – | Latitude, e.g. '40.1532'. |
| longitude | – | – | Longitude, e.g. '-82.4101'. |
| name | – | – | New place NAME (the short local name, e.g. 'Cedar Flat'). Omit to leave unchanged. |
| parent | – | – | Handle or gramps_id of the ENCLOSING place (e.g. the county a city sits in). Must already exist -- never created from a name. Replaces the current single enclosure; refused if the place carries sever… |
| place | string | yes | Place handle or gramps_id (e.g. 'P0001'). |
| place_type | – | – | New place type: 'Country', 'State', 'County', 'City', 'Town', 'Village', 'Parish', 'Farm', 'Building', etc., or a custom type the tree already has. Omit to leave unchanged. |
| remove_parent | boolean | – | Clear the enclosure instead of setting one. |
| title | – | – | New full TITLE (e.g. 'Cedar Flat, Brannock County, Ohio, USA') -- the string event-place resolution matches against. |
No output schema declared.
No examples provided.
update_research_task ~321
Change a research task's status, priority, privacy or attributes, or add to its description. Each attribute is replaced, never added beside the old one, so Gramps Web shows the value set. add_attribute would append a second Status that Gramps Web ignores. A private task's description note is private too; making the task public leaves a private note private unless private_note=false. Refuses a source that is not a task.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| attributes | – | – | More source attributes, name to value, e.g. {'Bears-On': 'I0035'}. Status and Priority have parameters of their own. A null value removes the attribute. |
| note_append | – | – | A paragraph to add to the task's description note, e.g. '2026-10-05: letter sent'. |
| priority | – | – | New priority. |
| private | – | – | True makes the task and its description note private. False makes the task public; a private note stays private unless private_note is false. |
| private_note | – | – | Set the description note's private flag yourself. Omitted, the note follows a private task and is never made public. |
| status | – | – | New status. |
| task | string | yes | The task's handle or gramps_id, e.g. 'S1501'. |
No output schema declared.
No examples provided.
update_source ~114
Edit an existing source's title, author, publication info, and/or abbreviation. Only the fields you provide are changed; the rest are left as-is.
| Name | Type | Req | Description |
|---|---|---|---|
| abbreviation | – | – | New abbreviation. Omit to leave unchanged. |
| author | – | – | New author. Omit to leave unchanged. |
| publication_info | – | – | New publication info. Omit to leave unchanged. |
| source | string | yes | Source handle or gramps_id (e.g. 'S0001'). |
| title | – | – | New title. Omit to leave unchanged. |
No output schema declared.
No examples provided.
update_url ~287
Edit or remove ONE existing URL entry on a person, place, or repository. add_url can only append -- this corrects an entry already there (the classic case: a Find a Grave link filed under the wrong type). The other fields on the object are untouched.
| Name | Type | Req | Description |
|---|---|---|---|
| allow_new_type | boolean | – | Accept a type that is neither a Gramps standard type nor one of the tree's custom types, creating it as a new custom type. Only when meant: a near-miss is refused with the closest names. |
| description | – | – | New link description. Omit to keep. |
| match | string | yes | Case-insensitive substring identifying WHICH url entry to edit, tested against each entry's path and description (e.g. 'findagrave.com/memorial/123'). Must match exactly one entry; matching none or s… |
| object_type | string | yes | Type of the object: 'person', 'place', or 'repository' only. |
| remove | boolean | – | Remove the matched entry instead of editing it. |
| target | string | yes | Handle or gramps_id of the object. |
| url | – | – | New URL path. Omit to keep. |
| url_type | – | – | New URL type, e.g. 'Web Home', 'Web Search', or a custom type the tree already has. Omit to keep. |
No output schema declared.
No examples provided.
verify_tree ~503
Run Gramps' own genealogical plausibility checks over the whole tree. This is a different audit from the citation ones. `list_unsourced_facts` asks whether a claim has evidence; this asks whether a claim is possible — a mother bearing a child at nine, a marriage lasting 120 years, a date that will not parse. A wrong date can be impeccably sourced, so these catch what a citation sweep cannot. Leave the thresholds alone on a first run; the server's defaults are the conventional ones. Tighten a specific bound when chasing a specific class of error. May run in the background, in which case a task_id comes back — poll it with get_job.
| Name | Type | Req | Description |
|---|---|---|---|
| estimate_age | boolean | – | Estimate missing or inexact dates when checking ages. Finds more, at the cost of guessing. |
| flag_invalid_dates | boolean | – | Report dates the parser cannot read. |
| max_age_at_death | – | – | Flag a death later than this age. Server default 90. |
| max_age_to_marry | – | – | Flag a marriage older than this. Server default 50. |
| max_child_birth_span | – | – | Flag a longer span of one couple's births. Default 25. |
| max_children_father | – | – | Flag a man with more children than this. Default 15. |
| max_children_mother | – | – | Flag a woman with more children than this. Default 12. |
| max_father_age | – | – | Flag a father older than this. Server default 65. |
| max_husband_wife_age_gap | – | – | Flag a wider spousal age gap. Server default 30. |
| max_mother_age | – | – | Flag a mother older than this. Server default 48. |
| max_spouses | – | – | Flag more spouses than this. Server default 3. |
| max_widowhood_years | – | – | Flag a longer widowhood before remarriage. Default 30. |
| max_years_between_children | – | – | Flag a longer gap between siblings. Default 8. |
| min_age_to_marry | – | – | Flag a marriage younger than this. Server default 17. |
| min_father_age | – | – | Flag a father younger than this. Server default 18. |
| min_mother_age | – | – | Flag a mother younger than this. Server default 17. |
| tree_id | string | – | Tree to check. Leave empty to use the tree these credentials are bound to, which is the usual case. |
No output schema declared.
No examples provided.
How do I install the Gramps Evidence MCP server?
Gramps Evidence runs locally as a PyPI package, launched with uvx gramps-evidence-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.
pypi · gramps-evidence-mcp
claude mcp add ianderso-gramps-evidence-mcp -- uvx gramps-evidence-mcp
What is the Gramps Evidence MCP server?
Gramps Evidence is an MCP server listed in the public MCP registry as io.github.ianderso/gramps-evidence-mcp. Read/write a self-hosted Gramps Web family tree where every fact carries a citation. This page covers its PyPI package (gramps-evidence-mcp).
Is the Gramps Evidence MCP server safe to use?
Gramps Evidence scores 79 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.
What tools does the Gramps Evidence MCP server expose?
Gramps Evidence exposes 97 tools: add_person, add_event_to_person, add_family, add_source, add_citation, and 92 more. Their descriptions and schemas cost roughly 17,227 tokens of context every time the server is loaded.
Is the Gramps Evidence MCP server still maintained?
Gramps Evidence is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.
What licence is the Gramps Evidence MCP server under?
Gramps Evidence declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.
What did VerifyMCP test on the Gramps Evidence MCP server?
VerifyMCP ran 15 checks on Gramps Evidence, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about Gramps Evidence: Malware scan. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.