gramps-ez-mcp
An easy-to-use MCP (Model Context Protocol) server to interact with Gramps genealogy family trees. This package provides a bridge between AI assistants and your Gramps database, enabling natural language queries about your family tree.
Installation
Install the package using pip:
pip install gramps-ez-mcp
Overview
gramps-ez-mcp is an MCP server that exposes your Gramps genealogy database through a standardized protocol. It allows AI assistants and chatbots to query and explore your family tree data using natural language.
The server provides tools for:
- Searching for people by name
- Retrieving person details (birth, death, events, etc.)
- Navigating family relationships (parents, children, spouses)
- Accessing family and event information
- Querying the home person
Configuration
Basic Configuration
The MCP server can be configured using command-line arguments or through MCP client configuration files.
Command-Line Usage
gramps-ez-mcp DBNAME [OPTIONS]
Arguments:
DBNAME: Name of the Gramps database tree to open (required)
Options:
--transport {stdio,sse}: Transport method to use (default:stdio)--host HOST: Host for SSE transport (default:localhost)--port PORT: Port for SSE transport (default:8000)
Examples:
# Use stdio transport with a database
gramps-ez-mcp "Gramps Example"
# Specify a custom database name
gramps-ez-mcp "My Family Tree"
# Use SSE transport on a custom port
gramps-ez-mcp "Gramps Example" --transport sse --port 9000
MCP Client Configuration
For use with MCP-compatible clients (like ez-mc-chatbot), create a configuration file:
Example: ez-config.json
{
"model": "openai/gpt-4o-mini",
"model_parameters": {
"temperature": 0.0
},
"mcp_servers": [
{
"name": "gramps-ez-mcp",
"description": "Gramps EZ MCP server for genealogy chats",
"command": "gramps-ez-mcp",
"args": ["Gramps Example"]
}
]
}
Replace "Gramps Example" with your actual Gramps database name.
Usage Examples
Using with ez-mc-chatbot
The ez-mc-chatbot is a command-line chatbot that can interact with MCP servers. Here's how to use it with gramps-ez-mcp:
-
Install ez-mc-chatbot (if not already installed):
pip install ez-mc-chatbot
-
Create a configuration file (e.g.,
examples/ez-config.json):{ "model": "openai/gpt-4o-mini", "model_parameters": { "temperature": 0.0 }, "mcp_servers": [ { "name": "gramps-ez-mcp", "description": "Gramps EZ MCP server for genealogy chats", "command": "gramps-ez-mcp", "args": ["Gramps Example"] } ] }
-
Run the chatbot:
ez-mc-chatbot --config examples/ez-config.json
-
Example queries you can ask:
- "Who is the home person in my family tree?"
- "Search for people named John Smith"
- "What is his birth date?"
- "Who are the children of John?"
- "Find the mother of Sarah Anderson"
Example Conversation
You: Who is the home person in my family tree?
Assistant: I'll look up the home person for you.
[Uses get_home_person tool]
The home person is John Doe (born 1950-01-15).
You: Who are their children?
Assistant: Let me find the children of John Doe.
[Uses get_children_of_person tool]
John Doe has 2 children:
- Jane Doe (handle: abc123)
- Bob Doe (handle: def456)
Available Tools
The following tools are available through the MCP server:
Person Tools
-
get_person(person_handle: str)- Get complete data dictionary for a person by their handle
- Returns: Dictionary with all person data
-
search_people_by_name(name: str, page: int = 1, page_size: int = 10)- Search for people by name (partial match, case-insensitive)
- Supports pagination
- Returns: List of matching person dictionaries
-
get_home_person()- Get the home person data from the database
- Returns: Dictionary with home person data
Relationship Tools
-
get_father_of_person(person_handle: str)- Get the father's data for a person
- Returns: Dictionary with father's data
-
get_mother_of_person(person_handle: str)- Get the mother's data for a person
- Returns: Dictionary with mother's data
-
get_children_of_person(person_handle: str)- Get list of children handles for a person's main family
- Returns: List of child handles (strings)
Date and Place Tools
-
get_person_birth_date(person_handle: str)- Get birth date as a string
- Returns: Birth date string
-
get_person_death_date(person_handle: str)- Get death date as a string
- Returns: Death date string
-
get_person_birth_place(person_handle: str)- Get birth place as a string
- Returns: Birth place string
-
get_person_death_place(person_handle: str)- Get death place as a string
- Returns: Death place string
Family and Event Tools
-
get_family(family_handle: str)- Get family data by family handle
- Note: Family handles are different from person handles
- Returns: Dictionary with family data
-
get_person_event_list(person_handle: str)- Get list of event handles associated with a person
- Returns: List of event handles (strings)
-
get_event(event_handle: str)- Get event data by event handle
- Returns: Dictionary with event data
-
get_event_place(event_handle: str)- Get the place associated with an event
- Returns: Place string
Requirements
- Python 3.8 or higher
- Gramps (genealogy software)
- MCP-compatible client (for using the server)
Troubleshooting
Database Not Found
If you get an error that the database was not found:
- Verify the database name matches exactly (case-sensitive)
- Check that the database exists in your Gramps data directory
- Use the exact name as shown in Gramps
License
This project is licensed under the GNU General Public License version 2 (GPL-2.0). See the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
Links
- Homepage: https://github.com/dsblank/gramps-ez-mcp
- Repository: https://github.com/dsblank/gramps-ez-mcp
- Bug Tracker: https://github.com/dsblank/gramps-ez-mcp/issues
Metadata
Release files for gramps-ez-mcp 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gramps_ez_mcp-0.0.1.tar.gz | 24.6 kB | Without provenance | Details for gramps_ez_mcp-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gramps_ez_mcp-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for gramps_ez_mcp-0.0.1-py3-none-any.whl |
Total release size: 48.8 kB
Release files / gramps_ez_mcp-0.0.1.tar.gz
| Download URL | gramps_ez_mcp-0.0.1.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8696e8604956345af9bae22885d94ca14944c62a0773e4e8124d988789d5223f
|
|
BLAKE2b-256 checksum How to use checksums |
e4eb2fe16f737c8ac91d5671ac2e62c06b9c9718fa00530408292a7a518bb230
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Release files / gramps_ez_mcp-0.0.1-py3-none-any.whl
| Download URL | gramps_ez_mcp-0.0.1-py3-none-any.whl |
|---|---|
| Size | 24.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c8aaa7f38c0a646e0a574bdf39d45066d28a4ad522f72d64d00ae1323acdd2e
|
|
BLAKE2b-256 checksum How to use checksums |
2f347c5dab38e0652441c0df0a45cef97e769445f7b5b9fe24ab39b31218cd56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Security for gramps-ez-mcp 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.