Gramps MCP - AI-Powered Genealogy Research & Management

Without Gramps MCP

Genealogy research with AI assistants is limited and frustrating:

• No direct access to your family tree data

• Manual data entry and research across multiple platforms

• Generic genealogy advice without context of your specific family

• No ability to automatically update or maintain your research

With Gramps MCP

Gramps MCP provides AI assistants with direct access to your Gramps genealogy database through a comprehensive set of tools. Your AI assistant can now:

• Smart Search: Find people, families, events, places, and sources across your entire database

• Data Management: Create and update genealogy records with proper validation

• Tree Analysis: Trace descendants, ancestors, and family connections

• Relationship Discovery: Explore family connections and research gaps

• Tree Information: Get comprehensive tree statistics and track changes

Add Gramps MCP to your AI assistant and transform how you research family history:

No more manual data entry, no context switching between apps, no generic genealogy advice.

• Connect to your Gramps Web API

• Install Gramps MCP in your AI assistant

• Start intelligent genealogy research with natural language

Features

16 Genealogy Tools

Search & Retrieval (3 tools)

• 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 (9 tools)

• 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 (4 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

Installation

Requirements

• Gramps Web server with your family tree data - Setup Guide

• Docker and Docker Compose

• MCP-compatible AI assistant (Claude Desktop, Cursor, etc.)

Quick Start

1. Ensure Gramps Web is Running:

   • Follow the Gramps Web setup guide to get your family tree online

   • Note your Gramps Web URL, username, and password

   • Find your tree ID under System Information in your Gramps Web interface

2. Start the Server:

That's it! The MCP server will be running at http://localhost:8000/mcp

Alternative: Run Without Docker

If you prefer to run the server directly with Python:

1. Setup Python Environment:

2. Run the Server:

The HTTP server will be available at http://localhost:8000/mcp, while stdio runs directly in the terminal.

Environment Configuration

Create a .env file with your Gramps Web settings:

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop MCP configuration file (claude_desktop_config.json):

Using Docker (works with both pre-built and local images):

Using uv directly (if running without Docker):

OpenWebUI

OpenWebUI recommends using the mcpo proxy to expose MCP servers as OpenAPI endpoints.

With uv:

With Docker:

Claude Code

HTTP Transport:

Stdio Transport (direct connection, more efficient):

Transport Choice: Use stdio for better performance and direct integration with CLI tools like Claude Code. Use HTTP when you need the server to handle multiple clients or prefer web-based access.

Other MCP Clients

For any other MCP client, use the HTTP transport endpoint:

Architecture

Core Components

Technology Stack

• MCP Python SDK: Model Context Protocol implementation

• FastAPI: HTTP server for MCP transport

• Pydantic: Data validation and serialization

• httpx: Async HTTP client for API communication

• PyJWT: JWT token authentication

• python-dotenv: Environment configuration

Usage Examples

Basic Search Operations

Data Creation and Updates

Genealogy Analysis

Tree Information & Statistics

Security

• JWT token authentication with automatic refresh

• Environment-based credential management

• Input validation using Pydantic models

• Secure HTTP transport with proper error handling

• No sensitive data exposed in tool responses

Troubleshooting

Common Issues

Connection refused errors: Ensure your Gramps Web API server is running and accessible at the configured URL.

Authentication failures: Verify your username and password are correct and the user has appropriate permissions.

Tool timeout errors: Check your network connection and consider increasing timeout values for large datasets.

Docker issues: Ensure Docker and Docker Compose are installed and running.

Debug Mode

To enable debug logging, check your application logs with:

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Related Projects

• Gramps - Free genealogy software

• Gramps Web API - Web API for Gramps

• Model Context Protocol - Standard for AI tool integration

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up the development environment

• Running tests and maintaining code quality

• Submitting pull requests

• Reporting issues and requesting features

Community & Support

• Bug Reports & Feature Requests: GitHub Issues

• Questions & Discussions: GitHub Discussions

• Documentation: Project Wiki

Acknowledgments

• The Gramps Project team for creating excellent genealogy software

• Anthropic for developing the Model Context Protocol

• The genealogy research community for inspiration and feedback