Gramps MCP

🚀 Gramps MCP - 由人工智能驱动的家谱研究与管理

Gramps MCP 借助一套全面的工具，为人工智能助手提供对 Gramps 家谱数据库的直接访问。它能助力人工智能助手实现智能搜索、数据管理、树状分析、关系发现等功能，改变你研究家族历史的方式。

🚀 快速开始

前置条件

• 拥有包含家族树数据的 Gramps Web 服务器 - 设置指南
• 安装 Docker 和 Docker Compose
• 配备兼容 MCP 的人工智能助手（如 Claude Desktop、Cursor 等）

快速上手

1. 确保 Gramps Web 已运行：

   • 按照 Gramps Web 设置指南 将家族树数据上线。
   • 记录 Gramps Web 的 URL、用户名和密码。
   • 在 Gramps Web 界面的系统信息中找到树 ID。

2. 启动服务器：

# 下载配置文件
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
# 使用你的 Gramps Web API 凭证编辑 .env 文件

# 启动服务器
docker-compose up -d

完成以上步骤后，MCP 服务器将在 http://localhost:8000/mcp 运行。

替代方案：不使用 Docker 运行

如果你倾向于直接使用 Python 运行服务器，可以按照以下步骤操作：

1. 设置 Python 环境：

# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖项
uv sync

2. 运行服务器：

# HTTP 传输（适用于基于 Web 的 MCP 客户端）
uv run python -m src.gramps_mcp.server

# 标准输入输出传输（适用于基于 CLI 的 MCP 客户端）
uv run python -m src.gramps_mcp.server stdio

HTTP 服务器将在 http://localhost:8000/mcp 可用，而标准输入输出将直接在终端中运行。

环境配置

创建一个 .env 文件，并配置你的 Gramps Web 设置：

# 你的 Gramps Web 实例（来自步骤 1）
GRAMPS_API_URL=https://your-gramps-web-domain.com  # 不要加 /api 后缀 - 会自动添加
GRAMPS_USERNAME=your-gramps-web-username
GRAMPS_PASSWORD=your-gramps-web-password
GRAMPS_TREE_ID=your-tree-id  # 在 Gramps Web 的系统信息中找到此 ID

✨ 主要特性

16 种家谱工具

搜索与检索（3 种工具）

• find_type - 使用 Gramps 查询语言对任何实体类型（个人、家庭、事件、地点、来源、引用、媒体、存储库）进行通用搜索。
• find_anything - 对所有家谱数据进行文本搜索（匹配字面文本，而非逻辑组合）。
• get_type - 通过 ID 获取特定个人或家庭的全面信息。

数据管理（9 种工具）

• create_person - 创建或更新个人记录。
• create_family - 创建或更新家庭单元。
• create_event - 创建或更新生活事件。
• create_place - 创建或更新地理位置。
• create_source - 创建或更新来源文档。
• create_citation - 创建或更新引用。
• create_note - 创建或更新文本笔记。
• create_media - 创建或更新媒体文件。
• create_repository - 创建或更新存储库记录。

分析工具（4 种工具）

• tree_stats - 获取树的统计信息。
• get_descendants - 查找某人的所有后代。
• get_ancestors - 查找某人的所有祖先。
• recent_changes - 跟踪数据的最近修改。

📦 安装指南

依赖环境

• Gramps Web 服务器：用于存储家族树数据，可参考 设置指南 进行配置。
• Docker 和 Docker Compose：用于容器化部署 Gramps MCP。
• MCP 兼容的 AI 助手：如 Claude Desktop、Cursor 等。

安装步骤

1. 连接到 Gramps Web API：确保 Gramps Web 服务器正常运行，并记录其 URL、用户名、密码和树 ID。
2. 安装 Gramps MCP 到 AI 助手：可以选择使用 Docker 或直接使用 Python 进行安装。
3. 开始智能家谱研究：使用自然语言与 AI 助手进行交互，开展家谱研究。

不同安装方式

使用 Docker 安装

# 下载配置文件
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

# 编辑 .env 文件，配置 Gramps Web API 凭证
# 启动服务器
docker-compose up -d

直接使用 Python 安装

# 安装 uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖项
uv sync

# 启动服务器
# HTTP 传输
uv run python -m src.gramps_mcp.server
# 标准输入输出传输
uv run python -m src.gramps_mcp.server stdio

环境配置

创建 .env 文件，配置 Gramps Web 相关信息：

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

💻 使用示例

基础用法

Find all people with the surname "Smith" born in Ireland

Show me recent changes to the family tree in the last 30 days

高级用法

Create a new person record for Patrick O'Brien, born 1845 in Cork, Ireland

Add a marriage event for John and Mary Smith on June 15, 1870 in Boston

Find all descendants of Margaret Kelly and show their birth locations

Show me statistics about my family tree - how many people, families, and events

What recent changes have been made to my family tree in the last week?

📚 详细文档

MCP 客户端配置

Claude Desktop

在 claude_desktop_config.json 文件中添加以下配置： 使用 Docker：

{
  "mcpServers": {
    "gramps": {
      "command": "docker",
      "args": ["exec", "-i", "gramps-mcp-gramps-mcp-1", "python", "-m", "src.gramps_mcp.server", "stdio"]
    }
  }
}

直接使用 uv：

{
  "mcpServers": {
    "gramps": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.gramps_mcp.server", "stdio"],
      "cwd": "/path/to/gramps-mcp"
    }
  }
}

OpenWebUI

使用 mcpo 代理 将 MCP 服务器作为 OpenAPI 端点暴露： 使用 uv：

uvx mcpo --port 8000 -- uv run python -m src.gramps_mcp.server stdio

使用 Docker：

uvx mcpo --port 8000 -- docker exec -i gramps-mcp-gramps-mcp-1 uv run python -m src.gramps_mcp.server stdio

Claude Code

HTTP 传输：

claude mcp add --transport http gramps http://localhost:8000/mcp

标准输入输出传输：

# 使用 Docker
claude mcp add --transport stdio gramps "docker exec -i gramps-mcp-gramps-mcp-1 sh -c 'cd /app && python -m src.gramps_mcp.server stdio'"
# 直接使用 uv
claude mcp add --transport stdio gramps "uv run python -m src.gramps_mcp.server stdio"

其他 MCP 客户端

使用 HTTP 传输端点：

{
  "mcpServers": {
    "gramps": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

🔧 技术细节

核心组件

src/gramps_mcp/
|-- server.py           # 支持 HTTP 传输的 MCP 服务器
|-- tools.py            # 工具注册与导出
|-- client.py           # Gramps Web API 客户端
|-- models.py           # Pydantic 数据模型
|-- auth.py             # JWT 身份验证
|-- config.py           # 配置管理
|-- tools/              # 模块化工具实现
|   |-- search_basic.py
|   |-- search_details.py
|   |-- data_management.py
|   |-- tree_management.py
|   `-- analysis.py
|-- handlers/           # 数据格式化处理程序
`-- client/             # API 客户端模块

技术栈

• MCP Python SDK：用于实现模型上下文协议。
• FastAPI：作为 MCP 传输的 HTTP 服务器。
• Pydantic：进行数据验证和序列化。
• httpx：用于 API 通信的异步 HTTP 客户端。
• PyJWT：实现 JWT 令牌身份验证。
• python-dotenv：管理环境配置。

📄 许可证

本项目采用 GNU Affero 通用公共许可证 v3.0 进行许可，请查看 LICENSE 文件以获取详细信息。

相关项目

• Gramps - 免费的家谱软件。
• Gramps Web API - Gramps 的 Web API。
• Model Context Protocol - 人工智能工具集成标准。

贡献指南

我们欢迎各方贡献！请查看 贡献指南 以了解：

• 开发环境的设置方法。
• 测试运行和代码质量维护。
• 提交拉取请求的流程。
• 问题报告和功能请求的方式。

社区与支持

• 问题报告与功能请求：GitHub Issues
• 问题讨论：GitHub Discussions
• 文档资料：项目维基

致谢

• Gramps 项目团队开发了出色的家谱软件。
• Anthropic 公司开发了模型上下文协议。
• 家谱研究社区提供了灵感和反馈。