Gramps and Chatbots

Development
1

There are now a few options to use modern chatbot AI systems with Gramps, and so I thought I would list and highlight their uses. This post gives pointers and brief summary of the projects. If I left any out (or I made any mistakes), please let me know.

Note: some of the Gramps addons require additional Python packages. This hasn’t worked very well in the past, but there is a planned fix for a future release (maybe 6.1) so those addons should work much better without issue.

The projects:

Gramps Web API

The Gramps Web API has support for a AI Agent, and Gramps Web uses
it. It requires an OpenAI-compatible LLM connection, and uses Pydantic
AI infrastructure. It currently has 9 read-only tools:

  • get_current_date
  • search_genealogy_database
  • get_person
  • get_family
  • get_event
  • get_place
  • filter_people
  • filter_events
  • filter_families

The search_genealogy_database is a sophisticated function that uses
either full-text search or vector similarity search against
pre-indexed representations of all Gramps objects, with the LLM
choosing the mode.

Resources

Gramps MCP

Gramps MCP also uses Gramps Web API under the hood. It has:

  • Universal search using Gramps Query Language (from the gramps_ql package)
  • Full-text search across all entities
  • CRUD (Create, Read, Update, and Delete) operations for all major Gramps objects (person, family, event, place, source, etc.)
  • Tree analysis tools (descendants, ancestors, statistics)
  • Change tracking and relationship discovery

Tools, in detail

These tools allow reading data, and writing data.

Search & Retrieval

  • find_type - Universal search for any entity type (person, family, event, place, source, citation, media, repository) using Gramps Query Language
  • find_anything - Text search across all genealogy data (matches literal text, not logical combinations)
  • get_type - Get comprehensive information about specific persons or families by ID

Data Management

  • create_person - Create or update person records
  • create_family - Create or update family units
  • create_event - Create or update life events
  • create_place - Create or update geographic locations
  • create_source - Create or update source documents
  • create_citation - Create or update citations
  • create_note - Create or update textual notes
  • create_media - Create or update media files
  • create_repository - Create or update repository records

Analysis Tools

  • tree_stats - Get tree statistics and information
  • get_descendants - Find all descendants of a person
  • get_ancestors - Find all ancestors of a person
  • recent_changes - Track recent modifications to your data

Gramps MCP is a clever and powerful implementation, building on the
independence of Gramps Web API. But that does make it more complicated
to use for other uses outside of Gramps Web (or outside of web use in
general).

Resources

Gramps EZ MCP

Gramps EZ MCP is a server that supports 14 tools. It uses some modern
Gramps features (like JSON), but also uses the slower SimpleAccess
API. MCP is a very useful API, and allows access to Gramps data from
outside of gramps.

A companion library of reusable database functions, libchatfuncs, was started alongside it. Development has since shifted toward in-process addons like GrampsAssistant, where the MCP layer is not needed — though the libchatfuncs tools may eventually be folded in there.

Resources

GrampsChat

GrampsChat is an OpenAI-based Agent that has 13 tools, and requires
litellm. Under the hood, it uses Gramps SimpleAccess. Gramps chat
was my first attempt at building a chatbot in Gramps desktop. I’ll
probably remove this in favor of GrampsAssistant (below).

Resources

ChatWithTree

ChatWithTree is a well-maintained addon with 15 read-only tools:

  • start_point
  • get_person
  • get_family
  • get_children_of_person
  • get_mother_of_person
  • get_father_of_person
  • get_person_birth_date
  • get_person_death_date
  • get_person_birth_place
  • get_person_death_place
  • get_person_event_list
  • get_event
  • get_event_place
  • get_child_in_families
  • find_people_by_name

It shares a similar approach to GrampsChat — both require litellm and use SimpleAccess under the hood — but ChatWithTree has a substantially different architecture. One notable characteristic: it opens its own separate database connection rather than plugging into the running Gramps session, which means it cannot control or update the Gramps UI.

Resources

GrampsAssistant

Gramps Assistant is a PR at the moment, but I hope to finish it up soon. It has no Python dependencies (no litellm required) and is wired directly into the running Gramps Gtk desktop session, so it knows which person is currently selected and can control the Gramps UI. It can also write Gram.py Scripts that can do additional functions (such as change data).

It has 26 tools, grouped roughly as:

Database queries — look up people, families, events, and statistics by Gramps ID or by relation to the active person:
get_person_details, get_active_person, get_home_person, get_database_statistics, get_person_events, get_children, get_siblings, get_ancestors, is_person_alive, find_relationship

UI control — navigate the Gramps window and apply sidebar filters so results appear on screen:
switch_to_view, search_in_view, get_view_results, set_active_person, edit_active_person, filter_people, filter_families, filter_events, filter_places, filter_sources, filter_citations, filter_media, filter_repositories, filter_notes

Scripting — write and execute a Gram.py Script for complex or custom queries; the generated code is shown to the user so they can learn and re-run it themselves:
execute_script

Web — look up historical context on Wikipedia:
search_wikipedia

Gramps Assistant tools don’t actually filter data or edit data (as the tool names might suggest) but rather uses the Gramps UI to do those things. The guiding idea is to surface Gramps’ own capabilities rather than duplicate them in functions that the user has no access to. (Suggestions welcome!)

Resources

2

hi @dsblank , just a heads up, i have not really maintained the gramps mcp much since the first release. As honestly the landscape shifted and after testing, and then talking with all of you here, it did not seem the best way forward.

The issues with MCP is that they are basically accessing a full rest api of an app, and that all that information is then stored in your context, and with something like Gramps Web that context is huge, so it overflows and makes the llm dumb from the get go.

I have been looking into some other methods, but been working on other projects in the meanwhile. The thing that I would go forward with, is to transform the mcp into just a simple authentication layer to the gramps web api. and then use a skill that explains both how a familytree is build and maintained, and have a skill per entity explaining how to call the api (fetching api info, not storing) to perform the action. This basically moves the maintenance and proper error logging into the api, instead of the mcp (something I was struggling with, as i was replicating all the rules of the api, and was hard to maintain with changes.) Some more info on this train of thought: https://medium.com/@alonisser/mcp-is-dead-or-mcp-vs-skills-revisited-daaa51b9a519

No promises from my side when i can build this new mcp+skill but it is in my pipeline with 500 other ideas. But if anyone else wants to take a shot at it, you are welcome.

3

Thanks for the update! And I agree with your assessment.

4

Amazing summary, thanks. Gramps Web v26.6 will be released later today, leveraging the API improvements already listed, plus some UI tweaks.

What I find super interesting about recent developments in agentic AI is that frontier models are getting so powerful that the agents’ “harness” - or even MCPs - are getting less important. In Gramps Web API v3.8 released in March this year, the REST API documentation was switched from a manually generated one to an automatically generated one. One of the motivations was to make sure it is 100% correct, so agents can rely on it. Every Gramps Web API instance now has an openapi.json that you can point an agent to, which tells it everything that can be done with the API, without the need for tool definitions or an MCP. Using jq, it can browse the JSON in a structured manner.

So, for power users/developers, there are almost no limits to what they can do with AI.

The built-in AI assistant in Gramps Web has a different scope of course - it is meant to answer questions by users with no technical knowledge about how AI agents work. What’s next on the roadmap there is to allow it to modify/add data, so you can use it as a data entry tool. I think it’s quite easy to implement, since the infrastructure is already there.

Related issue: [Feature Request] Native AI Chat "Write/Edit" Capabilities via Tool Calling (to preserve User Context) · Issue #808 · gramps-project/gramps-web-api · GitHub

5

Interesting! Using a system like Claude Code, that probably would save on some tokens rather than having to read the endpoint code.

More importantly, that idea might be very useful in Gramps Assistant which can now write code (using the Gram.py Script API—a simplified interface inside Gramps, inspired by Isotammi Addons Supertools). I will investigate; thanks!