Skip to content
verify mcp Beta VerifyMCP is currently in beta. If you notice any issues, get in touch and we’ll put it right.

Gramps Evidence

PYPI · GRAMPS-EVIDENCE-MCP

Read/write a self-hosted Gramps Web family tree where every fact carries a citation.

0 this week 79 Trust /100

Last scanned (12 hours ago)

Scores higher than 76% of PyPI servers

Category Health and Science

Trust breakdown (7 categories)

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
What we tested

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 →

Changelog

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
Diagnostics

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 →

MCP tools · 97 exposed · ~17,227 tokens

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 →

Tool Tokens
add_alternate_name ~294

Add an alternate (non-primary) name to a person, cited to the record using it. Use for maiden/married names, aliases, anglicized forms, or nicknames-of-record. The person's primary name is left unchanged. Correct or remove one later with update_alternate_name.

NameTypeReqDescription
allow_new_typeboolean–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.
citation––The record that gives this form of the name. It goes on the name itself -- 'this record spells it so' -- not on the person. Cite an existing name with cite_object(object_type='name').
givenstring–Given/first name(s) for the alternate name.
name_prefixstring–Surname prefix, e.g. 'van', 'de'.
name_suffixstring–Suffix, e.g. 'Jr.', 'III'.
name_typestring–Kind of alternate name, e.g. 'Also Known As', 'Birth Name', 'Married Name'.
nicknamestring–Nickname.
personstringyesPerson handle or gramps_id (e.g. 'I0001').
surnamestring–Family name / surname.

No output schema declared.

No examples provided.

add_attribute ~169

Add a typed key/value attribute to an object. update_attribute changes or removes one already there.

NameTypeReqDescription
allow_new_typeboolean–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.
namestringyesAttribute type/name, e.g. 'Occupation', 'Identification Number', or a custom name the tree already has.
object_typestringyesType of the object: 'person', 'event', 'family', 'media', 'source', 'citation'.
targetstringyesHandle or gramps_id of the object.
valuestringyesAttribute value, e.g. 'Blacksmith'.

No output schema declared.

No examples provided.

add_child_to_family ~200

Add an existing person as a child of an existing family. Links the child both ways: a ChildRef is added to the family and the family is added to the child's parent-family list. The child must already exist. Duplicate children are skipped.

NameTypeReqDescription
allow_new_typeboolean–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.
childstringyesChild person handle or gramps_id.
familystringyesFamily handle or gramps_id (e.g. 'F0001').
frelstring–Relationship to the father, e.g. 'Birth', 'Adopted', 'Stepchild'.
mrelstring–Relationship to the mother, e.g. 'Birth', 'Adopted', 'Stepchild'.

No output schema declared.

No examples provided.

add_citation ~86

Create a standalone Citation on a Source (or reuse an existing one). Usually you don't call this directly -- pass a CitationInput to add_person / add_event_to_person / add_family instead, which creates the citation and attaches it to the fact in one step. Use this when you want a reusable citation handle to attach to several facts.

NameTypeReqDescription
citation–yesCitation details.

No output schema declared.

No examples provided.

add_dna_match ~240

Record a DNA match as evidence, cited to the test that found it. Stored as Gramps Web stores a match, so its interface and get_dna_matches read it back. Nothing is written unless the segments parse: unreadable data would otherwise record a match sharing no DNA. A match proves the two share DNA, not how they are related. Record any relationship separately, with its own evidence.

NameTypeReqDescription
citation–yesThe test the match came from: source or source_title naming the company and kit, page for where the match is shown, confidence in the match itself. A new citation is always minted.
matchstringyesHandle or gramps_id of the matching person. Add them first if they are not in the tree.
personstringyesHandle or gramps_id of the tested person, whose results list the match.
segmentsstringyesThe shared segments as the testing company exports them: rows of chromosome, start, stop, centiMorgans, SNPs, comma- or tab-separated, with an optional side of M, P or U. A header row is tolerated.

No output schema declared.

No examples provided.

add_event_ref ~276

Share an existing event with another person, in a role. For one census entry, residence or burial that several people took part in: each references the same event, so its citations and later corrections serve all of them. Refused if the person already has it; update_event_ref edits that reference. A new fact is add_event_to_person.

NameTypeReqDescription
allow_new_typeboolean–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––Attributes of this person's reference: what is theirs alone, e.g. {'As enumerated': '<their line on the sheet>', 'Age': '34'}. A name is matched against standard names, the tree's, and those on the e…
eventstringyesHandle or gramps_id of the EXISTING event, e.g. 'E0007'.
personstringyesHandle or gramps_id of the person to add the event to.
rolestring–The person's role in it: 'Primary', 'Witness', 'Informant', 'Godparent', 'Family', 'Clergy', or a custom role the tree already has.

No output schema declared.

No examples provided.

add_event_to_family ~118

Add a dated/placed event (fact) to an existing family. Use for family-level facts: marriage, divorce, residence, census. The event is added with the 'Family' role. Cite it to the record establishing the fact.

NameTypeReqDescription
event–yesThe event to add (type, date, place, citation).
familystringyesFamily handle or gramps_id (e.g. 'F0001').
require_citationboolean–Require a citation (default). False records it UNSOURCED.

No output schema declared.

No examples provided.

add_event_to_person ~148

Add a dated/placed event (fact) to an existing person. Use for facts beyond birth/death: residence, occupation, census, baptism, immigration, marriage-adjacent events, etc. The event's citation should point at the record establishing the fact. Adding a 'Birth'/'Death' event will set the person's primary birth/death reference if not already set.

NameTypeReqDescription
event–yesThe event to add (type, date, place, citation).
personstringyesPerson handle or gramps_id (e.g. 'I0007').
require_citationboolean–Require a citation (default). False records it UNSOURCED.

No output schema declared.

No examples provided.

add_family ~248

Create a family linking parents and children, with an optional cited marriage. All members must already exist (create them first with add_person). Creating the family automatically links each person's family/parent-family lists, so you don't need to update the individuals separately. Cite the marriage event to a marriage record where possible.

NameTypeReqDescription
allow_new_typeboolean–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.
children––Children: handles or gramps_ids, each a birth child of both parents, or {person, frel, mrel} for a stepchild, adopted or foster child.
father––Father: handle or gramps_id.
marriage––Optional marriage event; type defaults to 'Marriage'. Cite it.
mother––Mother: handle or gramps_id.
relationshipstring–Family relationship type, e.g. 'Married', 'Unmarried', 'Civil Union'.
require_citationboolean–Require a citation on the marriage event (default).

No output schema declared.

No examples provided.

add_media ~184

Upload a document as a standalone Media object, reusing an identical file already in the tree. One image, one Media object -- then attach it wherever it belongs with attach_media(media_ref=...) and cite it once per fact it proves. Uploading the same photograph once per person it depicts is the duplicate pattern that later has to be unpicked by hand.

NameTypeReqDescription
dedup_by_checksumboolean–Reuse an existing Media object if the identical file is already in the tree. Leave True.
descriptionstringyesWhat the document IS -- archival identity, not the person it mentions ('1900 US census, Cedar Flat, Brannock Co., Ohio, ED 12 sheet 4A'). Files are stored under checksum names.
file_pathstringyesLocal path to the image, PDF, audio or video file to upload.

No output schema declared.

No examples provided.

add_note ~196

Create a research/general note, optionally attached to an object. Use notes for research logs, reasoning about conflicting evidence, or transcriptions. Attach to a person/event/source by giving target + target_type. Any length is written in one call; a server error says whether anything was.

NameTypeReqDescription
allow_new_typeboolean–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.
note_typestring–Note type, e.g. 'General', 'Research'.
target––Optional object handle/gramps_id to attach the note to.
target_type––Type of the target: 'person', 'family', 'event', 'source', 'citation', 'place', 'repository', 'media'.
textstringyesThe note text.

No output schema declared.

No examples provided.

add_person ~284

Create a new person, optionally with cited birth and/or death events. Use this to add someone to the tree. Good practice: attach the birth event with a citation to the *specific* record that proves it (a birth or baptism certificate, a census entry), setting the citation's confidence honestly. If you only have a legacy-tree hint with no underlying record, either omit the event or set require_citation=False so it's flagged for follow-up. Returns the new person's handle and gramps_id.

NameTypeReqDescription
birth––Optional birth event. Include a citation unless recording as unsourced. The event type defaults to 'Birth'.
death––Optional death event; type defaults to 'Death'.
gender––female, male, or unknown.
givenstringyesGiven/first name(s), e.g. 'John Robert'.
name_prefixstring–Surname prefix, e.g. 'van', 'de'.
name_suffixstring–Suffix, e.g. 'Jr.', 'III'.
require_citationboolean–If True (default), any birth/death event MUST carry a citation or the call fails. Set False to record the event anyway, stamped with the UNSOURCED attribute so list_unsourced_facts can find it later.
surnamestring–Family name / surname.

No output schema declared.

No examples provided.

add_place ~289

Create a place deliberately, with a type and a parent. Use this instead of letting a place appear as a side effect of naming one in an event. That route produces an untyped, unparented place whose title is the bare string you typed, which is how duplicate hierarchies start.

NameTypeReqDescription
allow_new_typeboolean–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.
codestring–Postal or FIPS code.
latitudestring–Latitude, decimal degrees.
longitudestring–Longitude, decimal degrees.
namestringyesThe place's own name, e.g. 'Cedar Flat'.
parentstring–Handle or gramps_id of an existing enclosing place. Must already exist — it is never created for you.
place_typestring–Gramps place type: Town, City, County, State, Country, Parish, Farm, Building, and so on, or a custom type the tree already has.
titlestring–Full display title, e.g. 'Cedar Flat, Brannock, Ohio, USA'. Defaults to the name. This is what event place matching compares against, so set it properly.

No output schema declared.

No examples provided.

add_repository ~165

Create a Repository (an institution or place that holds sources). Repositories sit at the top of the evidence model: Repository -> Source -> Citation -> fact. Create these for archives, libraries, cemeteries, or websites you'll cite sources from.

NameTypeReqDescription
allow_new_typeboolean–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.
namestringyesRepository name, e.g. 'National Archives (NARA)'.
repository_typestring–Type: 'Library', 'Archive', 'Cemetery', 'Church', 'Web site', etc.
url––Optional website URL.

No output schema declared.

No examples provided.

add_research_task ~253

Add a research task to Gramps Web's own task list (its Tasks view). Written exactly as Gramps Web's New Task form writes one: a Source tagged ToDo, Status 'Open', a Priority, and the description as a To Do note. A task is a to-do, never evidence: never cite it.

NameTypeReqDescription
allow_new_typeboolean–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.
descriptionstring–Details. Stored as the task's first note, type To Do.
priority––high, medium or low.
privateboolean–Mark the task and its note private.
tags––Tags besides ToDo, found or created by exact name, e.g. ['Probate'].
titlestringyesWhat to do, in one line, as the Tasks list shows it.

No output schema declared.

No examples provided.

add_source ~240

Create a Source (a body of evidence: a record set, book, certificate, website). In the Gramps evidence model a Source is what you cite *through* a Citation. Create the source once, then create citations against it for each fact it supports. Optionally link it to a Repository (where the source is held).

NameTypeReqDescription
abbreviation––Short abbreviation.
allow_new_typeboolean–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.
author––Author/creator of the source.
call_number––Call number / reference within the repository.
media_typestring–Medium of the source at that repository, e.g. 'Book', 'Film', 'Electronic'. Only used with repository.
publication_info––Publication info (publisher, date, series).
repository––Repository handle/gramps_id that holds this source.
titlestringyesSource title, e.g. '1900 U.S. Federal Census'.

No output schema declared.

No examples provided.

add_url ~210

Add a web URL to a person, place, or repository. Only these three object types carry a URL list. For sources/citations, record a web address as an attribute (add_attribute) instead.

NameTypeReqDescription
allow_new_typeboolean–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.
descriptionstring–Optional link description.
object_typestringyesType of the object: 'person', 'place', or 'repository' only.
targetstringyesHandle or gramps_id of the object.
urlstringyesThe URL, e.g. 'https://www.findagrave.com/memorial/123'.
url_typestring–URL type: 'Web Home', 'Web Search', 'E-mail', 'FTP', or a custom type the tree already has.

No output schema declared.

No examples provided.

assess_living ~171

Ask the server whether a person is probably still alive, and why. The server walks relatives to decide, so it handles people with no dates of their own — someone undated whose children died a century ago. Use it before publishing or sharing anything, and use `explain` when you want to see the reasoning rather than just the verdict. Note this is advisory. Bulk output is filtered by this server's own rule regardless of what this returns.

NameTypeReqDescription
average_generation_gap––Years per generation used when estimating.
explainboolean–Also return the estimated birth and death dates and which relative they were derived from.
max_age_probably_alive––Age beyond which a person is presumed dead.
personstringyesHandle or gramps_id of the person.

No output schema declared.

No examples provided.

attach_media ~275

Attach an image or document to an object -- a new upload, or one already in the tree. With file_path, the bytes are uploaded into the tree's managed media directory (so don't point at files you don't want copied); if that exact file is already present it is reused rather than duplicated. With media_ref, an existing Media object is linked. One image should be ONE Media object, linked from each object it belongs to and cited once per fact it proves. Uploading the same photograph separately for the husband and the wife creates duplicates that have to be unpicked later. The write is verified afterwards: `verified: false` means nothing attached, whatever the rest of the result says.

NameTypeReqDescription
descriptionstring–What the document IS, in archival terms. Only used when uploading a new file.
file_path––Absolute path to a local image, PDF, audio or video file to upload. Use this OR media_ref.
media_ref––Handle or gramps_id of a Media object ALREADY in the tree. Prefer this when the same document supports several people.
targetstringyesObject handle/gramps_id to attach media to.
target_typestring–Type of the target object: 'person', 'event', 'source', etc.

No output schema declared.

No examples provided.

check_family_links ~110

Audit the links between people and families, in both directions. Finds a family a person lists twice, a child a family lists twice, a link one side holds and the other lacks, and links to objects that do not exist. Each finding says how to repair it. Reports only.

NameTypeReqDescription
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
limitinteger–Maximum findings to return.

No output schema declared.

No examples provided.

cite_child_link ~208

Cite the parent-child link itself, on the family's ChildRef. "This child belongs to these parents" is a DIFFERENT claim from "this child appears in this record", and it needs its own citation object. Reusing the child's existing citation handle makes the link inherit a confidence that was assigned to another claim entirely, so the link displays a confidence its evidence never earned. Note what a ChildRef citation asserts: BOTH sides of the link. A census naming only the mother does not document the father. Where only one parent is evidenced, cite that parent's relationship instead of implying both.

NameTypeReqDescription
childstringyesThe child's person handle or gramps_id.
citation–yesCitation for the PARENTAGE claim. Create a new one (source + page + confidence) rather than reusing a citation handle from elsewhere -- see the warning below.
familystringyesFamily handle or gramps_id (e.g. 'F0001').

No output schema declared.

No examples provided.

cite_event ~134

Attach a citation to an event that ALREADY exists. Use this to source an event you didn't create with an inline citation -- e.g. one added through the Gramps web UI, or an unsourced event surfaced by list_unsourced_facts. The citation is resolved/created (existing handle/id, or an inline source_title + page + confidence) and appended to the event's citation list (no duplicates). Does not change any other event field.

NameTypeReqDescription
citation–yesCitation to attach to the event.
eventstringyesEvent handle or gramps_id (e.g. 'E0007').

No output schema declared.

No examples provided.

cite_object ~251

Attach a citation to any object that carries one -- not just events. cite_event covers facts; this covers the rest. The important case is the FAMILY, whose citation supports a claim no event makes: that these two people were a couple. Person-level citations are for evidence about the individual as a whole (an identity document) rather than about one dated fact -- prefer citing the specific event where one exists. A NAME is cited with object_type='name': "this record gives this spelling" is narrower than evidence about the person. To cite a parent-child link, use cite_child_link: that is a different claim and needs its own citation.

NameTypeReqDescription
citation–yesCitation to attach.
name––With object_type='name': which of the person's names, e.g. {'surname': 'Bittner', 'type': 'Birth Name'} or {'primary': true}. Must match exactly one.
object_typestringyesperson, family, event, place, media, source, citation, or name (one of a person's names: ref is the person, name says which).
refstringyesHandle or gramps_id of the object to cite.

No output schema declared.

No examples provided.

consolidated_timeline ~218

Merge several people or families into one chronological timeline. The way to see a household move together through censuses, or to check whether a family's events are mutually consistent. Carries the same citation count and confidence per event as get_timeline, with an uncited_count across the whole set.

NameTypeReqDescription
anchorstring–Handle or gramps_id of a central person. They are included, and each event gets anchor_age, their age at it; age is always the age of the person whose event it is.
event_typesstring–Comma-delimited event type names to include, e.g. 'Birth,Death,Census'. Omit for all.
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
limitinteger–Maximum events.
object_typestring–Either 'person' or 'family'.
targetsarrayyesHandles or gramps_ids to merge into one timeline.

No output schema declared.

No examples provided.

consult_reference ~222

Consult the legacy GEDCOM reference layer for HINTS (never authoritative). Searches the configured Ancestry/FamilySearch exports and returns, per file, matching individuals and their claimed facts. Crucially, each fact is flagged whether the legacy tree attached a source, with the source text if present -- so you can distinguish 'they cite an actual death certificate' from 'unsourced guess'. These are UNTRUSTED hints: use them to decide what real record to hunt for, then create the fact in the tree citing that record -- do not copy a hint in as a sourced fact. Probably-living people are withheld and counted.

NameTypeReqDescription
approx_birth_year––Approximate birth year to disambiguate (± a few years).
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
namestringyesName (or name substring) to look up.
year_toleranceinteger–Allowed birth-year difference when matching.

No output schema declared.

No examples provided.

create_filter ~182

Save a reusable custom filter built from Gramps' own rules. Worth doing for a selection you will run repeatedly — an audit scope, a branch of the tree — because the filter then has a name rather than being retyped each time.

NameTypeReqDescription
commentstring–Note on the filter's purpose.
functionstring–How rules combine: 'and', 'or', or 'one'.
invertboolean–Return everything the rules do NOT match.
namestringyesFilter name, used to apply it later.
namespacestringyesSingular, capitalised: Person, Family, Event, Place, Citation, Source, Repository, Media, Note.
rulesarrayyesRules, each {'name': <rule>, 'values': [...], 'regex': false}. Rule names come from list_filter_rules.

No output schema declared.

No examples provided.

db_stats ~39

Counts of people, families, events, citations, sources, repositories, places, media, and notes in the tree. A quick health/overview check.

Input schema present but exposes no named parameters.

No output schema declared.

No examples provided.

delete_filter ~56

Delete a saved custom filter. Deletes the filter definition only. Nothing in the tree is touched.

NameTypeReqDescription
namestringyesName of the filter to delete.
namespacestringyesPlural namespace, e.g. 'people'.

No output schema declared.

No examples provided.

delete_object ~164

Permanently delete an object from the tree by handle or gramps_id. DESTRUCTIVE. The server also removes every reference to it. Refused when it is the only holder of a note or image (pass carry_to to move them), and for a source with citations, which the server would delete with it.

NameTypeReqDescription
carry_to––Another object of the same type to receive the notes and images that only this one holds. Without it, such a delete is refused.
object_typestringyesType to delete: 'person', 'family', 'event', 'place', 'source', 'citation', 'repository', 'media', 'note', 'tag'.
targetstringyesHandle or gramps_id of the object to delete.

No output schema declared.

No examples provided.

detach_object ~275

Remove a reference from an object: an event from a person, an image from a source, a tag, a note, a child from a family. The reference is removed; the object itself survives unless delete_if_orphan is set AND nothing else points at it -- which is checked, because deleting something other facts still reference leaves dangling handles behind.

NameTypeReqDescription
call_number––Repository only: detach just the link with this call number, when a source is held twice in one repository. Omit to detach every link.
childstringyesHandle or gramps_id of the thing to detach; a tag may be given by name.
child_kindstringyesWhat to detach: event, media, note, tag (removes a tag), citation, child (a person from a family), person (a person_ref), repository, enclosure (a parent of a place), or -- on a person, to repair a l…
delete_if_orphanboolean–Also delete the detached object if nothing else references it. Off by default -- detaching and deleting are different decisions.
parentstringyesIts handle or gramps_id.
parent_typestringyesType of the object holding the reference.

No output schema declared.

No examples provided.

event_span ~127

Measure the elapsed time between two events. The arithmetic behind most plausibility checks: age at marriage, years between a census and a death, how long a widow waited. Doing this by hand from two formatted date strings is where transcription errors hide.

NameTypeReqDescription
as_ageboolean–Phrase the result as an age rather than an interval.
event1stringyesHandle or gramps_id of the first event.
event2stringyesHandle or gramps_id of the second event.
precision––How many units to include (years, months, days).

No output schema declared.

No examples provided.

export_backup ~125

Write a full-tree export to disk. Take one before any bulk write. Cheap insurance: a few seconds and one file. A bulk write that goes wrong cannot always be undone transaction by transaction; a dump can be re-imported.

NameTypeReqDescription
dest_path––A new file in an existing directory; an existing file is never replaced. Omit for a timestamped file in the cache directory.
export_formatstring–'gramps' (Gramps XML, lossless -- use this for a safety dump), 'ged', 'json', or 'csv'.

No output schema declared.

No examples provided.

find_duplicates ~203

Find likely-duplicate objects. Reports only -- it never merges anything. Duplicates are not merely untidy: a duplicate SOURCE makes a single-sourced fact look corroborated, which is a false evidentiary claim. But the reverse error is just as real -- an index entry and the register page it indexes are TWO documents and must stay separate. This tool finds candidates; deciding which are truly the same document is yours. Merge with merge_objects.

NameTypeReqDescription
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
kindstringyesmedia_checksum (same file uploaded twice), source_title (same document entered twice), citation_page (same source+page cited more than once, flagging any graded differently), vital_events (a person w…
limitinteger–Max groups to return.

No output schema declared.

No examples provided.

get_ancestors ~94

Walk a person's ancestors up to N generations (a nested parents tree). Living/private ancestors appear as redacted stubs unless include_private is set.

NameTypeReqDescription
generationsinteger–How many generations up.
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
personstringyesRoot person handle or gramps_id.

No output schema declared.

No examples provided.

get_backlinks ~103

List everything that references this object, grouped by type. The right way to ask "is this source actually cited?", "which facts rest on this citation?", or "is it safe to delete this?" -- an object with zero backlinks is orphaned; one with backlinks will leave dangling references if deleted.

NameTypeReqDescription
object_typestringyesType of the object being pointed AT.
refstringyesHandle or gramps_id of that object.

No output schema declared.

No examples provided.

get_citation ~72

Read one citation: page, confidence, date, and its source. `cited_by_count` is the useful part. Zero means nothing references this citation — it is orphan debris, and `uncite` should have deleted it.

NameTypeReqDescription
citationstringyesHandle or gramps_id of the citation.

No output schema declared.

No examples provided.

get_descendants ~93

Walk a person's descendants up to N generations (a nested children tree). Living/private descendants appear as redacted stubs unless include_private is set.

NameTypeReqDescription
generationsinteger–How many generations down.
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
personstringyesRoot person handle or gramps_id.

No output schema declared.

No examples provided.

get_dna_matches ~159

List the DNA matches recorded against a person. Each match reports total shared centiMorgans and the largest single segment — the two figures a relationship estimate actually rests on — plus any common ancestor already identified. **DNA evidence works differently from documentary evidence.** A match proves a biological relationship exists; it does not say which one. Shared cM constrains the possibilities and rarely resolves them, and it says nothing about the paper trail. `unattributed_count` is the useful number: matches with no common ancestor identified are the open research.

NameTypeReqDescription
include_rawboolean–Include the unparsed note text the segments came from.
personstringyesHandle or gramps_id of the tested person.

No output schema declared.

No examples provided.

get_event ~60

Get an event: type, date, place handle, description, citation count, and attributes. Use to inspect an event before citing or editing it.

NameTypeReqDescription
eventstringyesEvent handle or gramps_id, e.g. 'E0001'.

No output schema declared.

No examples provided.

get_facts ~213

Read the tree's record-holders: oldest at death, youngest parent, most children. Superlatives across a set of people, not statistics about one person. An implausible holder — a father at eight, a death at 130 — is usually a data error, which makes this a quick plausibility check. Living and private people are excluded unless include_private is set. Slow: the server computes it all per call.

NameTypeReqDescription
include_privateboolean–Show living people and private records in full. Only when the user asks for them; they are withheld by default.
personstring–Handle or gramps_id a built-in person_filter is anchored on.
person_filterstring–Narrow the set: 'Ancestors', 'Descendants', 'DescendantFamilies' or 'CommonAncestor' of person, or a saved custom person filter's name. Omit for the whole tree.
rankinteger–Record-holders to return per statistic.

No output schema declared.

No examples provided.

get_family ~45

Get a family: relationship type, parent handles, child handles, event count.

NameTypeReqDescription
familystringyesFamily handle or gramps_id, e.g. 'F0001'.

No output schema declared.

No examples provided.

get_job ~110

Check whether a background job has finished, and whether it worked. Undo, verification, import and reindex are dispatched to a worker and answer before the work is done. Poll this until `finished` is true, then read `succeeded`. Submitting one of those operations and never checking leaves you assuming an outcome you have not seen.

NameTypeReqDescription
task_idstringyesThe task_id returned by whatever dispatched the work: undo_transaction, verify_tree, reindex_search or run_report.

No output schema declared.

No examples provided.

get_media ~84

Read one media object: path, mime type, checksum, description, date. `referenced_by_count` above one is usually correct — one image cited from every fact it proves. Several media objects sharing a checksum is the duplicate that `find_duplicates(kind='media_checksum')` hunts.

NameTypeReqDescription
mediastringyesHandle or gramps_id of the media object.

No output schema declared.

No examples provided.

get_note ~76

Read one note in full, with its type and what it is attached to. Notes hold the researcher's own reasoning — why a conflict was resolved one way, what a hard-to-read page actually said — so the text comes back whole rather than truncated.

NameTypeReqDescription
notestringyesHandle or gramps_id of the note.

No output schema declared.

No examples provided.

get_object ~125

Read any object's raw record -- including places, media, notes and citations, which have no shaped getter. Returns the record as stored, which is what you want before editing one. For people and sources the shaped getters (get_person, get_source) are easier to read.

NameTypeReqDescription
keys––Comma-separated fields to return. Omit for the whole record.
object_typestringyesperson, family, event, place, source, citation, repository, media, note, or tag.
refstringyesHandle or gramps_id.

No output schema declared.

No examples provided.

get_person ~100

Get full detail for one person: name, gender, events (with citation counts), attributes, family links, and media count. Direct lookup is allowed even for living/private individuals (this is your own local tool); only bulk/list tools filter them. Use this to inspect someone before adding facts, or to check whether an event is already cited.

NameTypeReqDescription
personstringyesPerson handle or gramps_id, e.g. 'I0001'.

No output schema declared.

No examples provided.

get_place ~84

Read one place: name, title, type, enclosure, coordinates and URLs. The `enclosed_by` handles are the jurisdictional chain. A place with none is orphaned in the hierarchy, which is usually a place that got minted from an event's place string rather than created deliberately.

NameTypeReqDescription
placestringyesHandle or gramps_id of the place.

No output schema declared.

No examples provided.

get_record_history ~156

Who added, edited or deleted one record, and when, newest first. Each change names its transaction: get_transaction shows what it changed. Before gramps-webapi 3.22 the whole transaction log is read instead: slower, and the result says so.

NameTypeReqDescription
field––Only the changes to this field of the stored record, each with its value before and after: 'parent_family_list', 'primary_name.first_name'.
limitinteger–Most recent changes to return.
object_typestringyesperson, family, event, place, source, citation, repository, media, note, or tag.
refstringyesHandle or gramps_id. A deleted record by its handle.

No output schema declared.

No examples provided.

get_relationship ~144

Work out how two people in the tree are related. Returns the relationship in words plus the generation distance from each person to their common ancestor. `related` is false when no common ancestor was found within the search depth — which is a finding in itself if you expected one.

NameTypeReqDescription
all_pathsboolean–Report every relationship path, not just the closest. Use this when two people may be related more than one way.
depth––Generations to search. Server default if omitted.
person1stringyesHandle or gramps_id of the first person.
person2stringyesHandle or gramps_id of the second person.

No output schema declared.

No examples provided.

get_report_options ~67

Read one report's default options before running it. Reports take a full option dict, not a partial one, so the way to change a single setting is to read these defaults and override that key.

NameTypeReqDescription
report_idstringyesReport id, e.g. 'ancestor_report'.

No output schema declared.

No examples provided.

Install

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

# add to Claude Code
claude mcp add ianderso-gramps-evidence-mcp -- uvx gramps-evidence-mcp
Common questions

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.