Gedcom MCP (Sjmatta)

GEDCOM MCP服务器

A. FastMCP 服务器，使AI助手能够从GEDCOM文件中查询家谱数据。

特性

• 24个MCP工具 进行全面的家谱研究：

核心工具：

- get_home_person -获取树木所有者的记录 - get_statistics -树统计数据（计数、日期范围、顶级姓氏） - get_individual -按ID获取基本详细信息 - get_biography -为一个人提供全面的叙事套餐 - get_family -获取家庭信息（配偶、子女、婚姻）

导航工具：

- get_parents -找个人的父母 - get_children -从所有婚姻中获得所有孩子 - get_spouses -获取所有配偶的婚姻详细信息 - get_siblings -有兄弟姐妹（父母相同） - get_ancestors -祖先树可达N代 - get_descendants -N代以下的树 - traverse -用于自定义导航的通用图遍历

搜索与发现：

- search_individuals -按名称搜索（部分匹配） - semantic_search -基于向量的语义搜索（例如，“苏格兰农民”） - search_nearby -GIS邻近搜索或边界框搜索

关系分析：

- get_relationship -计算两个人之间的关系 - detect_pedigree_collapse -查找多次出现的祖先 - find_associates -粉丝俱乐部技巧（朋友、同事、邻居）

时间线和事件：

- get_timeline -按时间顺序排列的个人生活事件 - get_military_service -查找树中的所有退伍军人

地名和姓氏分析：

- get_place_cluster -让所有人连接到一个位置 - get_surname_origins -分析姓氏分布和地理起源

自然语言：

- query -自然语言问题（非代理MCP客户端的回退）

• 4 MCP资源:

- gedcom://individual/{id} -按ID分类的个人记录 - gedcom://family/{id} -按ID列出的家庭记录 - gedcom://stats -树木统计 - gedcom://surnames -所有有计数的姓氏

• 针对大文件进行了优化 -启动时解析GEDCOM一次，在内存中构建索引以实现快速搜索

可选功能

语义搜索 启用自然语言语义匹配（例如，“宾夕法尼亚州的煤矿工人”、“从爱尔兰移民”）：

export SEMANTIC_SEARCH_ENABLED=true

需要句子转换（包含在依赖项中）。第一次运行构建嵌入（大文件约15-30秒），后续运行从缓存加载。

GIS邻近搜索 查找距离某个位置X英里以内或某个区域边界框内的人。默认情况下启用后台地理编码。结果包括：

• 接近模式：在一个点的X英里范围内
• 内模式：在区域的边界框内

无需配置-地理编码在启动时自动运行并缓存结果。

遥测与观测 使用Arize Phoenix进行OpenTetry跟踪，用于调试和性能监控：

export PHOENIX_ENABLED=true

需要运行Phoenix服务器（请参阅 .env.example 和 docker-compose.yml).

安装

使用uvx（推荐，无需安装）

uvx gedcom-server --gedcom-file /path/to/your/tree.ged

使用uv工具安装

uv tool install gedcom-server
gedcom-server --gedcom-file /path/to/your/tree.ged

来源

git clone git@github.com:sjmatta/gedcom-mcp.git
cd gedcom-mcp
uv sync

配置

服务器需要GEDCOM文件路径。您可以选择指定一个“家庭成员”（树所有者）。

配置选项

CLI参数覆盖环境变量。

如果 --home-person 如果未指定，服务器将自动检测树中连接最多的个体。

例子

# Using CLI arguments
gedcom-server --gedcom-file ~/Documents/family.ged

# Using environment variables
export GEDCOM_FILE=~/Documents/family.ged
gedcom-server

# With explicit home person
gedcom-server -f ~/Documents/family.ged -p @I500@

Claude桌面配置

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

使用uvx（推荐）

{
  "mcpServers": {
    "gedcom": {
      "command": "uvx",
      "args": ["gedcom-server"],
      "env": {
        "GEDCOM_FILE": "/path/to/your/tree.ged"
      }
    }
  }
}

使用uv工具安装

{
  "mcpServers": {
    "gedcom": {
      "command": "gedcom-server",
      "args": ["--gedcom-file", "/path/to/your/tree.ged"]
    }
  }
}

来源

{
  "mcpServers": {
    "gedcom": {
      "command": "/path/to/gedcom-mcp/.venv/bin/python",
      "args": ["-m", "gedcom_server"],
      "env": {
        "GEDCOM_FILE": "/path/to/your/tree.ged"
      }
    }
  }
}

GEDCOM文件

服务器支持GEDCOM 5.5.1格式，可以从以下位置导出：

• Ancestry.com
• 家庭搜索
• 明星脸
• 爷爷
• 大多数其他家谱软件

发展

# Install dev dependencies
uv sync

# Run tests
uv run poe test

# Run linter
uv run poe lint

# Run formatter
uv run poe format

# Run type checker
uv run poe typecheck

# Run all checks
uv run poe check

# Start server (requires GEDCOM_FILE env var)
uv run poe serve

有关详细的开发说明，请参阅 贡献.md.

预提交钩子

预提交挂钩配置用于：

• 预承诺：ruff linting、ruff格式化、mypy类型检查
• 预推：pytest测试套件

安装挂钩：

uv run pre-commit install --install-hooks

许可证

MIT许可证-请参阅 许可证 了解详情。