Gramps MCP

🚀 Gramps MCP - AIを活用した系図研究と管理

Gramps MCPは、包括的なツールセットを通じて、AIアシスタントにGramps系図データベースへの直接アクセスを提供します。これにより、AIアシスタントは以下のことができます。

• スマート検索：データベース全体で人物、家族、出来事、場所、情報源を検索します。
• データ管理：適切な検証を行いながら、系図レコードの作成と更新を行います。
• 樹状分析：子孫、祖先、家族関係を追跡します。
• 関係性発見：家族関係と研究上のギャップを探索します。
• 樹状情報：包括的な樹状統計を取得し、変更を追跡します。

AIアシスタントにGramps MCPを追加することで、家族歴の研究方法を革新しましょう。

1850年以前にアイルランドで生まれたジョン・スミスのすべての子孫を検索する

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

2. サーバを実行する

# 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は直接ターミナルで実行されます。

環境設定

Gramps Webの設定を含む .env ファイルを作成します。

# あなたの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では、MCPサーバをOpenAPIエンドポイントとして公開するために mcpoプロキシ の使用を推奨しています。

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"

トランスポートの選択：Claude CodeのようなCLIツールとの直接統合やパフォーマンスが必要な場合は stdio を使用します。サーバが複数のクライアントを処理する必要がある場合や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：Model Context Protocolの実装
• FastAPI：MCPトランスポート用のHTTPサーバ
• Pydantic：データ検証とシリアライゼーション
• httpx：API通信用の非同期HTTPクライアント
• PyJWT：JWTトークン認証
• python-dotenv：環境設定

💻 使用例

基本的な検索操作

アイルランドで生まれた姓が「スミス」のすべての人物を検索する

過去30日間の家族樹状の最近の変更を表示する

データの作成と更新

1845年にアイルランドのコークで生まれたパトリック・オブライアンの新しい人物レコードを作成する

1870年6月15日にボストンでジョンとメアリー・スミスの結婚イベントを追加する

系図分析

マーガレット・ケリーのすべての子孫を検索し、彼らの出生地を表示する

樹状情報と統計

家族樹状に関する統計情報を表示する - 何人の人物、家族、出来事があるか

過去1週間で家族樹状にどのような最近の変更があったか？

セキュリティ

• 自動更新付きのJWTトークン認証
• 環境ベースの資格情報管理
• Pydanticモデルを使用した入力検証
• 適切なエラー処理を備えた安全なHTTPトランスポート
• ツールの応答に機密データを公開しない

トラブルシューティング

一般的な問題

接続拒否エラー：Gramps Web APIサーバが実行されており、構成されたURLでアクセス可能であることを確認してください。

認証失敗：ユーザー名とパスワードが正しく、ユーザーに適切な権限があることを確認してください。

ツールのタイムアウトエラー：ネットワーク接続を確認し、大規模なデータセットの場合はタイムアウト値を増やすことを検討してください。

Dockerの問題：DockerとDocker Composeがインストールされており、実行されていることを確認してください。

デバッグモード

デバッグログを有効にするには、以下のコマンドでアプリケーションログを確認してください。

docker-compose logs -f

📄 ライセンス

このプロジェクトはGNU Affero General Public License v3.0の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

関連プロジェクト

• Gramps - 無料の系図ソフトウェア
• Gramps Web API - Gramps用のWeb API
• Model Context Protocol - AIツール統合の標準

コントリビューション

コントリビューションを歓迎します！詳細については コントリビューションガイド を参照してください。

• 開発環境のセットアップ
• テストの実行とコード品質の維持
• プルリクエストの提出
• 問題の報告と機能のリクエスト

コミュニティとサポート

• バグ報告と機能リクエスト：GitHub Issues
• 質問とディスカッション：GitHub Discussions
• ドキュメント：プロジェクトウィキ

謝辞

• 優れた系図ソフトウェアを作成したGrampsプロジェクトチーム
• Model Context Protocolを開発したAnthropic
• インスピレーションとフィードバックを提供した系図研究コミュニティ