GedcomMCP

GEDCOM MCP Server

Genealogy for AI Agents, by AI Agents

A robust MCP server for creating, editing and querying genealogical data from GEDCOM files. Works great with qwen-cli and gemini-cli

This project provides a comprehensive set of tools for AI agents to work with family history data, enabling complex genealogical research, data analysis, and automated documentation generation.

The server has been recently improved with fixes for critical bugs, enhanced error handling, and better code quality while maintaining full backward compatibility.

Some sample complex prompts:

   Load gedcom "myfamily.ged"
   Make a complete, detailled biography of  and his fammily. Use as much as you can from this genealogy, including any notes from him or his relatives. 
   You can try to find some info on Internet to complete the document, add some historical or geographic context, etc. Be as complete as possible to tell us a nice story, easy to read by everyone

or

  Create a new GEDCOM file - save it to "napo.ged"                                                                                                                                              
  Fetch the content of Napoleon I's Wikipedia page                                                                                                                                           
    1. Extract genealogical information about him and people mentioned on his page                                                                                                             
    2. Follow links to other people's Wikipedia pages to gather more information                                                                                                              
    3. Create a comprehensive genealogical record  with as much details as possible. Including birth/death dates and place, family relationships (parents, spouses, children...), occupation, etc, and including a note with the person wikipedia page address and important info about his life                                                                                                                    
    4. Repeat the same process with all people added by previous steps                                                                                                                       
   Continuously save the GEDCOM file as new people are added

or

   Load gedcom "myfamily.ged"
   What's shortest path from John Doe to Bob Smith ?
   And who are their common ancestors ?

Features

• Data Management: Load and parse GEDCOM files, add/edit people, families, events, and places
• Powerful Querying: Search across people, families, events, and places with flexible criteria
• Relationship Analysis: Find relationships between individuals, common ancestors, and family connections
• Family Trees: Generate multi-generational ancestor and descendant trees with detailed information
• Timeline Generation: Create chronological timelines of life events
• Data Analysis: Analyze genealogical data with comprehensive statistics, duplicate detection, and surname analysis
• Historical Context: Extract date ranges and historical period information
• Metadata Handling: Rich support for notes, sources, and detailed event information
• Data Validation: Validate date consistency and data integrity
• Batch Operations: Efficient bulk processing capabilities

Installation

1. Clone the repository:

``bash git clone https://github.com/airy10/GedcomMCP.git cd GedcomMCP ``

1. Install the required dependencies:

``bash pip install -r requirements.txt ``

Usage

To start the server with the default HTTP transport:

python src/gedcom_mcp/fastmcp_server.py

To start the server with stdio transport:

python src/gedcom_mcp/fastmcp_server.py --transport stdio

To specify a different host or port for the HTTP transport:

python src/gedcom_mcp/fastmcp_server.py --host 0.0.0.0 --port 8080

Running Tests

To run all tests:

python -m pytest tests/

To run tests with verbose output:

python -m pytest tests/ -v

To run a specific test file:

python -m pytest tests/test_gedcom_data_access.py

To run a specific test:

python -m pytest tests/test_gedcom_data_access.py::TestGedcomDataAccess::test_load_gedcom_file

Project Structure

• src/gedcom_mcp/: Main source code
• fastmcp_server.py: Main server application and tool definitions
• gedcom_context.py: GEDCOM parsing context and caching management
• gedcom_data_access.py: Data retrieval and extraction functions
• gedcom_data_management.py: Data modification and management functions
• gedcom_analysis.py: Statistical analysis and reporting functions
• gedcom_search.py: Relationship finding and path analysis
• gedcom_utils.py: Utility functions for data processing
• gedcom_constants.py: GEDCOM event and attribute definitions
• gedcom_date_utils.py: Advanced date parsing and validation
• gedcom_name_utils.py: Name parsing and normalization
• gedcom_place_utils.py: Place name normalization and geographic hierarchy
• gedcom_models.py: Data models and structures
• tests/: Comprehensive unit and integration tests
• requirements.txt: Project dependencies
• pyproject.toml: Build configuration
• prompts/: Template files for LLM prompt generation

Recent Improvements

This project has undergone significant improvements including:

• Fixed critical bugs in note processing and attribute handling
• Resolved syntax errors and improved code quality
• Enhanced error handling with better error messages
• Removed debug statements from production code
• Improved documentation consistency
• Maintained full backward compatibility
• All 99 automated tests continue to pass

Contributing

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them with descriptive messages
4. Push your changes to your fork
5. Create a pull request to the main repository

License

This project is licensed under the MIT License.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: airy10
• Source: airy10/GedcomMCP
• License: MIT

Install and usage instructions live in the source repository linked above.