MCP 服务器

gramps-ez-mcp

Enables natural language queries about family tree data from a Gramps genealogy database.

README

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

Setup

You will need the following:

An API key from a model provider (such as OpenAI, Anthropic, etc)
Gramps installed and working with a family tree (may also need pip install gramps)

For example, you might have in your environment:

export OPENAI_API_KEY="sk-..."

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-mcp-chatbot, Cursor, etc), you will need a configuration file.

For example, for ez-mcp-chatbot:

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-mcp-chatbot

The ez-mcp-chatbot is a command-line chatbot that can interact with MCP servers. Here's how to use it with gramps-ez-mcp:

Install ez-mcp-chatbot (if not already installed):
```
pip install ez-mcp-toolbox
```

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-mcp-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"

LLM Logging, Debugging, and Observability

If you would like for the ez-mcp-chatbot to create a log of what the MCP server is doing, you can log the interactions with the LLM by doing the following:

pip install opik

Then you can get an OPIK_API_KEY from https://www.comet.com/docs/opik/quickstart and set it:

export OPIK_API_KEY="..."

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