Gramps MCP Server

How to use

You connect your MCP client to the Gramps MCP server to perform natural language queries and manage your genealogy data. Start the server and then use an MCP client to issue requests like finding all descendants, creating or updating person records, or pulling tree statistics. Use plain language prompts to guide your AI assistant through data retrieval, updates, and analysis, and let the server validate and apply changes to your Gramps Web data.

How to install

Prerequisites you need before installation are a Gramps Web server with your family tree data, Docker and Docker Compose, and an MCP-compatible AI assistant (for example Claude Desktop or similar). After you prepare these, follow the steps to install and run Gramps MCP.

# Quick start using Docker

# Download the configuration
curl -O https://raw.githubusercontent.com/cabout-me/gramps-mcp/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/cabout-me/gramps-mcp/main/.env.example
cp .env.example .env
# Edit .env with your Gramps Web API credentials

# Start the server
docker-compose up -d

# MCP server will be available at http://localhost:8000/mcp

If you prefer to run without Docker, you can run the server directly with Python using the UV loop tool. You will still need to supply your Gramps Web credentials to connect to Gramps Web.

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies via UV (if needed)
uv sync

# Run the server (HTTP transport to expose MCP over HTTP)
uv run python -m src.gramps_mcp.server

# Run the server in stdio mode (CLI-based MCP clients)
uv run python -m src.gramps_mcp.server stdio

Configuration and runtime notes

Prepare environment variables for Gramps Web access and tree selection. The following values must be provided in a configuration file or environment to enable the server to reach your Gramps Web data.

# Environment variables for Gramps Web access
GRAMPS_API_URL=https://your-gramps-web-domain.com
GRAMPS_USERNAME=your-gramps-web-username
GRAMPS_PASSWORD=your-gramps-web-password
GRAMPS_TREE_ID=your-tree-id

Security and maintenance

The server uses JWT tokens for authentication and validates inputs to prevent malformed updates. Ensure credentials are stored securely, use encrypted transports for HTTP, and review access permissions regularly. Track changes with the built-in history and periodically verify data integrity.

Examples of common workflows

Use natural language prompts to perform end-to-end tasks such as locating all descendants of a person, updating a life event, or generating tree statistics for reporting.

Troubleshooting

If you encounter connection issues, verify that the Gramps Web API is running and reachable at the URL you configured. Check credentials, permissions, and ensure the MCP server is running with the expected transport (HTTP or stdio). Review logs for authentication failures or timeout issues and adjust network timeouts as needed.

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 for literal matches of text

get_type

Get comprehensive information about specific persons or families by ID

create_person

Create or update person records with validation

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

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