gramps-web-mcp

オープンソースの系図プラットフォーム Gramps Web 向けのコンパニオン MCP サーバーです。AI エージェントに、Model Context Protocol を通じて家系図への構造化されたツールベースのアクセスを提供します。

このプロジェクトは、スタンドアロンの系図 UI や Gramps Web の代替品ではありません。既存の Gramps Web インスタンスと一緒に実行してください。ユーザー、家系図、メディア、権限、系図編集 UI はすべて Gramps Web に残ります。

機能

• 57 の MCP ツール — 人物、家族、イベント、場所、情報源、引用、メモ、メディア、リポジトリ、タグの読み取り、作成、更新、削除

• 検索とブラウズ — 全文検索とページネーション付きオブジェクト一覧

• 親族関係ツール — 祖先、子孫、関係、タイムライン

• 複合ワークフロー — クイック追加人物、人物へのイベント追加、Gramps ID による検索

• 6 つの MCP リソース — タイプ語彙、入力ガイド、家系図メタデータ、名前設定、および視覚認識可能なエージェント向けのオプトインメディアサムネイル/ファイル

• メディア保護機能 — サイズ制限、MIME 許可リスト、プライベートレコードのデフォルト設定

• MCP プロンプト — 調査、人物/家族の追加、インポートのためのガイド付きワークフロー

• 複数のトランスポート — stdio（ローカルクライアント）、Streamable HTTP、レガシー SSE

• 読み取り専用モード — すべてのツールを表示したまま、作成、更新、削除の呼び出しをブロック

完全なリストはツールカタログを参照してください。

Related MCP server: ASPNET Core Debugging MCP Server

前提条件

• .NET 8 SDK（ローカル開発用）

• API アクセスが可能な実行中の Gramps Web インスタンス

• Docker（オプション、コンテナデプロイ用）

クイックスタート

ローカル開発（デモサーバー）

run-local-server.sh は、公開されている demo.grampsweb.org インスタンスに、既知のデモ認証情報（owner / owner）を使用して接続します：

./run-local-server.sh

サーバーは HTTP トランスポートで http://127.0.0.1:8080/mcp に起動します。ループバックのみにバインドする場合、API キーは不要です。

Docker

マルチアーキテクチャのプレビルドイメージ（linux/amd64、linux/arm64）が GitHub Container Registry に公開されています。Docker は自動的に適切なアーキテクチャを選択します。amd64 はほとんどの Unraid および x86 ホストをカバーし、arm64 は Apple Silicon および ARM SBC をカバーします：

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

イメージは Docker HEALTHCHECK、Unraid コンテナヘルスチェック、その他の稼働監視のために GET /health エンドポイントを公開します。MCP サーバーが Gramps Web に対して認証できる場合は HTTP 200 を、それ以外の場合は HTTP 503 を返します。デフォルトの公開レスポンスは最小限で、{ "status": "healthy" } または { "status": "unhealthy" } です。起動ログには、API に到達可能になった時点で Connected to Gramps Web at … のような行が含まれます。

イメージはデフォルトで Streamable HTTP（MCP_TRANSPORT=http）をポート 8080 で使用します。これは上記のコマンドで使用されているものです。コンテナを自分で起動するクライアント（MCP Registry インストールなど）は、代わりに -e MCP_TRANSPORT=stdio で stdio 経由で実行し、stdin を開いたままにします（docker run -i）。これが server.json で宣言されているモードです。

読み取り専用モードにするには、-e GRAMPS_READ_ONLY=true を追加します：

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid インストール

Unraid ユーザーは Community Applications から gramps-web-mcp をインストールできます。テンプレートソースは Scormave/gramps-web-mcp-unraid で管理されています。Unraid 固有のヘルプについては、Unraid フォーラムのサポートスレッドを参照してください。

基本的なセットアップ：

1. Unraid で Apps / Community Applications を開きます。

2. gramps-web-mcp を検索し、テンプレートをインストールします。

3. Gramps Web インスタンスに合わせて GRAMPS_API_URL、GRAMPS_USERNAME、GRAMPS_PASSWORD、GRAMPS_TREE_ID を設定します。MCP ポートがネットワーク上の他のマシンから到達可能な場合は、MCP_API_KEY を設定します。

4. デフォルトのコンテナポート 8080 をそのまま使用するか、別のホストポートにマッピングします。

5. コンテナを起動し、/health を確認します。サービスが Gramps Web に対して認証できると HTTP 200 を返し、デフォルトでは最小限の JSON レスポンスを返します。

最も簡単なペアリング方法は、Gramps Web と gramps-web-mcp を同じ Unraid Docker ネットワーク上で実行し、GRAMPS_API_URL を Gramps Web コンテナの URL に設定することです。クライアント向けの MCP エンドポイントは http://<unraid-host>:<mapped-port>/mcp です。

Gramps Web + MCP（Docker Compose）

同じホストと Docker ネットワーク上で Gramps Web と MCP サーバーを実行するには、docker-compose.example.yml を出発点として使用します：

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web はポート 5055 で公開され、MCP は 8080（/mcp および /health）で公開されます。Compose ネットワーク内では、MCP コンテナは http://grampsweb:5000 で Gramps Web に到達します。

Claude Desktop（MCPB 拡張機能）

Claude Desktop へのワンクリックインストールは、MCP Bundle（.mcpb）として GitHub Releases から入手できます。お使いのプラットフォームに合ったバンドルをダウンロードしてください：

1. 最新リリースから、お使いの OS に対応する .mcpb ファイルをダウンロードします。

2. ダブルクリックするか、Claude Desktop ウィンドウにドラッグ＆ドロップします。

3. Gramps Web の URL、ユーザー名、パスワード/トークン、ツリー UUID を入力します。

4. 最初のセッションでは 読み取り専用モード を有効にしたままにし、Claude にレコードを作成または編集させる場合のみ無効にします。

5. インストールを完了し、新しいチャットを開始します。

拡張機能は stdio 経由でローカルに実行され、マシンに .NET SDK は必要ありません。 パッケージの詳細は mcpb/README.md を、プライバシーポリシーは PRIVACY.md を参照してください。

バンドルをローカルでビルドするには：

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

MCP クライアント設定（手動）

stdio（例：Claude Desktop、Cursor）：

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

stdio サーバーを読み取り専用モードで実行するには、env に "GRAMPS_READ_ONLY": "true" を追加します。

HTTP（リモート / Docker）：

MCP クライアントを Streamable HTTP トランスポートで http://host:8080/mcp にポイントします。MCP_API_KEY が設定されている場合は、すべての MCP リクエストに Authorization: Bearer <key> または X-Api-Key: <key> として送信します。

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

視覚認識可能なエージェントは、ツール（GetMediaThumbnail、GetMediaFile）またはバイナリ MCP リソース（gramps://media/{handle}/thumbnail/{size}、gramps://media/{handle}/file）を通じてオプトインメディアを読み取ることができます。GetMediaFile は MIME タイプに応じて画像、音声、または埋め込み blob リソースコンテンツを返します。エンドツーエンドの分析は、MCP クライアントが型付きツールコンテンツまたはバイナリリソースコンテンツを対応するモデルに転送するかどうかに依存します。

設定

必須（Gramps 接続）

実行時モード

• GRAMPS_READ_ONLY：true に設定すると、ツールを表示したまま作成、更新、削除の呼び出しをブロックします。

• GRAMPS_MUTATION_SERIALIZE：このプロセス内で作成/更新/削除の HTTP 呼び出しを一度に 1 つずつ実行します。

• GRAMPS_MUTATION_MIN_INTERVAL_MS：複合ツール内のステップを含む、ミューテーション HTTP 呼び出し間の最小待機時間。

実行時の注意：

• GRAMPS_READ_ONLY=false は、サーバーが読み取り/書き込みモードで起動することを意味します。

• Claude Desktop MCPB 拡張機能は例外で、そのセットアップフォームはデフォルトで読み取り専用になり、初回使用をより安全にします。

• 書き込みの直列化とオプションのインターバルは、典型的な Gramps Web SQLite 家系図をエージェントの書き込みバーストから保護します。

• 書き込みゲートは プロセス内のみ です。複数の MCP レプリカ、Gramps Web UI、または他の API クライアント間での調整は行いません。

• 連続した編集で database is locked が発生する SQLite デプロイメントでは、GRAMPS_MUTATION_MIN_INTERVAL_MS=250 または 500 を設定してください。

• SQLite ロックエラーまたは上流の HTTP 429 が発生した場合、ミューテーションツールは汎用的な 500 ではなく、短いバックオフヒント付きの再試行可能な MCP エラーを返します。

• Gramps Web が PostgreSQL を使用しており、並列書き込みが必要な場合は、GRAMPS_MUTATION_SERIALIZE=false を設定します。

メディアファイルアクセス

メディアバイトツール/リソースはデフォルトで無効になっています。get_media はファイルダウンロードを有効にしなくてもメタデータに使用できます。

AI 分析には GetMediaThumbnail または gramps://media/{handle}/thumbnail/{size} を推奨します。完全なファイルは大きく機密性が高い可能性があり、同じサイズ、MIME、プライベートレコードチェックの対象となります。

正確なタイプと type/* ワイルドカードがサポートされています。デフォルトのメディア許可リストは image/jpeg,image/png,image/webp,image/avif,application/pdf です。

トランスポート

GRAMPS_API_URL、GRAMPS_USERNAME、GRAMPS_PASSWORD、GRAMPS_TREE_ID は通常通り設定します。

HTTP トランスポートの場合、レスポンスは SSE でストリーミングされます。プロトコルの詳細は Streamable HTTP 仕様 を参照してください。ASPNETCORE_URLS を設定してリスンアドレスを選択します。例：http://127.0.0.1:8080。

オプション（MCP トランスポート）

HTTP 認証

MCP_API_KEY が設定されている場合、すべての MCP HTTP/SSE エンドポイントはすべてのリクエストでキーを要求します。 GET /health は Docker やロードバランサーのプローブのために匿名のままです。

キーを生成:

openssl rand -base64 32

キーがなくてもサーバーは起動します（後方互換性あり）。待ち受けアドレスがループバック専用でない場合、MCP_API_KEY を設定するか、独自の認証を持つリバースプロキシを使用するか、ローカル専用で 127.0.0.1 にバインドすることを推奨する警告がログに記録されます。

Docker 内部では、ASPNETCORE_URLS は通常 http://0.0.0.0:8080 であるため、ホストがポートを 127.0.0.1 のみに公開している場合でも警告が表示されます。これは外部アクセスが既に制限されている場合に想定される動作です。

開発

dotnet test

CONTRIBUTING.md および開発者ガイドを参照してください。

ドキュメント

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md を参照してください。

セキュリティ

脆弱性を報告するには、SECURITY.md を参照してください。

プライバシーポリシー

Claude Desktop 拡張はローカル MCP サーバーです。設定した Gramps Web インスタンスにのみデータを送信し、分析データや会話データを収集しません。詳細は PRIVACY.md を参照してください。

ライセンス

Copyright (c) Scormave

このプロジェクトは GNU Affero General Public License v3.0 (AGPL-3.0-or-later) の下でライセンスされています。これはネットワークサーバーソフトウェアであるため、改変版をホストする場合は、ネットワークを介してやり取りするユーザーに対応するソースコードを利用可能にする必要があります。