Gramps MCP

Gramps MCP-基于人工智能的家谱研究与管理

无Gramps MCP

使用人工智能助手进行家谱研究是有限且令人沮丧的：

• 无法直接访问您的家谱数据
• 跨多个平台的手动数据输入和研究
• 没有特定家庭背景的通用家谱建议
• 无法自动更新或维护您的研究

使用Gramps MCP

Gramps MCP通过一套全面的工具为AI助手提供直接访问Gramps家谱数据库的权限。您的AI助手现在可以：

• 智能搜索：在整个数据库中查找人员、家庭、事件、地点和来源
• 数据管理：创建和更新家谱记录，并进行适当的验证
• 树分析：追踪后代、祖先和家庭关系
• 关系发现：探索家庭关系和研究差距
• 树信息：获取全面的树木统计数据并跟踪变化

将Gramps MCP添加到您的AI助手中，并改变您研究家族史的方式：

Search for all descendants of John Smith born in Ireland before 1850

Create a new person record for Mary O'Connor with birth date 1823 in County Cork

Find all families missing marriage dates and suggest research priorities

无需手动输入数据，无需在应用程序之间切换上下文，也无需通用的家谱建议。

• 连接到Gramps Web API
• 在您的AI助手中安装Gramps MCP
• 用自然语言开始智能家谱研究

特性

16家谱工具

搜索和检索（3个工具）

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

数据管理（9个工具）

• create_person -创建或更新人员记录
• create_family -创建或更新族单位
• create_event -创建或更新生活事件
• create_place -创建或更新地理位置
• create_source -创建或更新源文档
• 创建_初始化 -创建或更新引文
• create_note -创建或更新文本注释
• 创建媒体 -创建或更新媒体文件
• 创建存储库 -创建或更新存储库记录

分析工具（4个工具）

• tree_stats -获取树统计数据和信息
• get_descendants -查找一个人的所有后代
• get_ancestors -查找一个人的所有祖先
• 最近更改 -跟踪最近对数据的修改

安装

需求

• Gramps Web服务器 使用您的家谱数据- 安装指南
• Docker和Docker Compose
• MCP兼容的AI助手（克劳德桌面、光标等）

快速开始

1. 确保Gramps Web正在运行:

- 跟随 Gramps Web设置指南 在线获取您的家谱 - 记下您的Gramps Web URL、用户名和密码 - 在Gramps Web界面的系统信息下查找您的树ID

1. 启动服务器:

# 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服务器将在以下时间运行 http://localhost:8000/mcp

替代方案：不使用Docker运行

如果你更喜欢用Python直接运行服务器：

1. 设置Python环境:

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

# Install dependencies
uv sync

1. 运行服务器:

# HTTP transport (for web-based MCP clients)
uv run python -m src.gramps_mcp.server

# Stdio transport (for CLI-based MCP clients)
uv run python -m src.gramps_mcp.server stdio

HTTP服务器将在 http://localhost:8000/mcp，而stdio直接在终端中运行。

环境配置

创建一个 .env 使用Gramps Web设置的文件：

# Your Gramps Web instance (from step 1)
GRAMPS_API_URL=https://your-gramps-web-domain.com  # Without /api suffix - will be added automatically
GRAMPS_USERNAME=your-gramps-web-username
GRAMPS_PASSWORD=your-gramps-web-password
GRAMPS_TREE_ID=your-tree-id  # Find this under System Information in Gramps Web

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop MCP配置文件(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 （如果不使用Docker运行）：

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

OpenWeb用户界面

OpenWebUI建议使用 mcpo代理 将MCP服务器暴露为OpenAPI端点。

紫外线：

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

克劳德代码

HTTP传输：

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

标准运输 （直接连接，更高效）：

# Using 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'"

# Using uv directly (requires local setup)
claude mcp add --transport stdio gramps "uv run python -m src.gramps_mcp.server stdio"

运输选择： 使用 标准输入输出 以获得更好的性能并与Claude Code等CLI工具直接集成。使用 超文本传输协议 当您需要服务器处理多个客户端或更喜欢基于web的访问时。

其他MCP客户端

对于任何其他MCP客户端，请使用HTTP传输端点：

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

建筑

核心组件

src/gramps_mcp/
|-- server.py           # MCP server with HTTP transport
|-- tools.py            # Tool registry and exports
|-- client.py           # Gramps Web API client
|-- models.py           # Pydantic data models
|-- auth.py             # JWT authentication
|-- config.py           # Configuration management
|-- tools/              # Modular tool implementations
|   |-- search_basic.py
|   |-- search_details.py
|   |-- data_management.py
|   |-- tree_management.py
|   `-- analysis.py
|-- handlers/           # Data formatting handlers
`-- client/             # API client modules

技术栈

• MCP Python SDK：模型上下文协议实现
• 快速 API：用于MCP传输的HTTP服务器
• 派丹蒂克：数据验证和序列化
• httpx：用于API通信的异步HTTP客户端
• PyJWT：JWT令牌身份验证
• python dotenv：环境配置

使用示例

基本搜索操作

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?

安全

• JWT令牌身份验证，自动刷新
• 基于环境的凭证管理
• 使用Pydantic模型进行输入验证
• 通过适当的错误处理确保HTTP传输的安全
• 工具响应中没有暴露敏感数据

故障排除

常见问题

连接被拒绝错误：确保Gramps Web API服务器正在运行，并且可以通过配置的URL访问。

身份验证失败：验证您的用户名和密码是否正确，以及用户是否具有适当的权限。

刀具超时错误：检查您的网络连接，并考虑增加大型数据集的超时值。

Docker问题确保Docker和Docker Compose已安装并正在运行。

调试模式

要启用调试日志记录，请使用以下命令检查应用程序日志：

docker-compose logs -f

许可证

此项目根据GNU Affero通用公共许可证v3.0获得许可-请参阅 许可证 文件以获取详细信息。

相关项目

• 克 -免费家谱软件
• Gramps Web API -Gramps的Web API
• 模型上下文协议 -AI工具集成标准

贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 建立开发环境
• 运行测试并保持代码质量
• 提交拉取请求
• 报告问题和请求功能

社区与支持

• Bug报告和功能请求:
• 问题和讨论:
• 文档: 维基工程

致谢

• Gramps项目团队致力于打造卓越的家谱软件
• 用于开发模型上下文协议的Anthropic
• 家谱研究社区寻求灵感和反馈