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 公司開發了模型上下文協議。
• 家譜研究社區提供了靈感和反饋。