STARWARCLOUD STARWAR.AI
返回市场
格兰普斯-mcp

格兰普斯-mcp

作者：cabout-me15 星标更新：2025-09-14
安装使用来源：spider==github.com

项目介绍

Gramps MCP - 基于AI的家谱研究与管理

License Python MCP

没有 Gramps MCP

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

  • 无法直接访问您的家谱数据
  • 需要在多个平台上手动输入数据并进行研究
  • 提供通用的家谱建议，而没有针对您特定家庭的上下文
  • 无法自动更新或维护您的研究

使用 Gramps MCP

Gramps MCP通过一系列全面的工具，为AI助手提供了直接访问您的Gramps家谱数据库的能力。现在，您的AI助手可以：

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

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

查找所有在1850年前出生在爱尔兰的John Smith的后代

为Mary O'Connor创建一个新的个人记录，出生日期为1823年，在科克郡

查找所有缺少结婚日期的家庭，并提出研究优先级

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

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

功能

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
  • 兼容MCP的AI助手（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
# 编辑.env文件，填写您的Gramps Web API凭据

# 启动服务器
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
  1. 运行服务器：
# HTTP传输（用于基于Web的MCP客户端）
uv run python -m src.gramps_mcp.server

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

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

环境配置

创建一个.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的系统信息下找到这个

MCP客户端配置

Claude Desktop

添加到您的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"
    }
  }
}

OpenWebUI

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

Stdio传输（直接连接，更高效）：

# 使用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"

传输选择：使用stdio以获得更好的性能和与CLI工具如Claude Code的直接集成。当您需要服务器处理多个客户端或偏好基于Web的访问时，使用HTTP。

其他MCP客户端

对于任何其他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：异步HTTP客户端用于API通信
  • PyJWT：JWT令牌认证
  • python-dotenv：环境配置

使用示例

基本搜索操作

查找所有姓“Smith”且出生于爱尔兰的人

显示过去30天内对家谱树的最近更改

数据创建和更新

为Patrick O'Brien创建一个新的个人记录，出生于1845年的爱尔兰科克郡

为John和Mary Smith添加一个结婚事件，时间是1870年6月15日，在波士顿

家谱分析

查找Margaret Kelly的所有后代，并显示他们的出生地

树信息及统计

显示我的家谱树的统计数据 - 有多少人、家庭和事件

在过去一周里，我对我家谱树做了哪些更改？

安全性

  • 使用JWT令牌认证并自动刷新
  • 基于环境的凭证管理
  • 使用Pydantic模型进行输入验证
  • 使用安全的HTTP传输并正确处理错误
  • 工具响应中不暴露敏感数据

故障排除

常见问题

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

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

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

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

调试模式

启用调试日志，请检查应用日志：

docker-compose logs -f

许可证

此项目根据GNU Affero通用公共许可证v3.0许可 - 详情请参阅LICENSE文件。

相关项目

贡献

我们欢迎贡献！请参阅我们的贡献指南了解详情：

  • 设置开发环境
  • 运行测试并维护代码质量
  • 提交拉取请求
  • 报告问题和请求功能

社区和支持

致谢

  • Gramps项目团队，为创建优秀的家谱软件
  • Anthropic，为开发模型上下文协议
  • 家谱研究社区，为灵感和反馈