Gramps Web MCP

gramps-web-mcp

警告

2.3.1 以降に更新してください。 2.3.1 より前のバージョンでは、update_* ツールが、呼び出しで指定されていない保存済みデータを削除することがありました （#5）。以前のバージョンで ツリーを編集した場合は、 削除されたデータがないか確認してください。

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

このプロジェクトは、単独で動作する家系図 UI でも Gramps Web の代替でもありません。既存の Gramps Web インスタンスと併せて実行してください。ユーザー、家系図、メディア、権限、家系図編集 UI は、引き続き Gramps Web に維持されます。

[][install-vscode] [][install-vscode-insiders] [][install-cursor]

ボタンをクリックすると、VS Code または Cursor にサーバーが追加され、Docker イメージから起動されます。そのため、Docker がインストールされている必要があります。詳細は Docker で stdio 経由で実行するをご覧ください。Claude Desktop では、 MCPB 拡張機能をインストールしてください。

機能

• 最大32個のMCPツール — 人物、家族、イベント、場所、ソース、引用、メモ、メディア、リポジトリ、タグの読み取り、作成、更新、削除
• 検索と閲覧 — 全文検索とページ分割されたオブジェクト一覧表示。Gramps QLまたはGrampsのフィルタールール（ある人物と関係のあるすべての人、家族とのつながりがない人など）で絞り込めます
• 親族関係ツール — 先祖、子孫、関係、タイムライン
• リンクの段階的な変更 — linkMode を使ってイベント、子ども、引用、メモを1つずつ追加または削除し、ほかのリンクはすべて保持します
• 元に戻す — 後続の編集を上書きしたりリンクを壊したりしないことを確認したうえで、削除を含む編集履歴の1つのトランザクションを元に戻します
• 確認ダイアログ — MCP elicitationに対応したクライアントでは、delete_object と undo_change によってツリーが変更される前に、モデルではなくユーザーに確認を求めます
• Grampsでの表記に準拠した日付 — 範囲、以前／以後／頃、およびGrampsのすべての暦（1856-07-20 (Julian)）。Grampsが計算した並べ替え値とともに保存されます
• 8つのMCPリソース — 種別の語彙、入力ガイド、ツリーのメタデータ、名前の設定、フィルタールール、およびオプトインで利用できる、視覚機能に対応したエージェント向けのメディアプレビュー／ファイル
• メディアの保護対策 — サイズ制限、プライベート記録のデフォルト設定、EXIF/GPSメタデータを除去したプレビュー
• MCPプロンプト — 調査、つながりの発見、人物や家族の追加、インポート、リンクの変更、事実の引用に関するガイド付きワークフロー
• 複数のトランスポート — stdio（ローカルクライアント）、Streamable HTTP、レガシーSSE
• 読み取り専用モード — 読み取りツールのみを公開し、直接の変更呼び出しをブロックします

全項目については、ツールカタログをご覧ください。 1.xからアップグレードする場合は、保存済みのツール呼び出しとクライアント設定を更新するため、2.0移行ガイドに従ってください。

認証、メディアのダウンロード、ヘルスチェックを含む、Gramps Webへのすべての送信リクエストでは、このアプリケーションが User-Agent: gramps-web-mcp/<version> (+https://github.com/Scormave/gramps-web-mcp) で自動的に識別されます。バージョンはアプリケーションのビルドから取得されるため、設定は不要です。

前提条件

• .NET 10 SDK（ローカル開発用）
• APIアクセスが可能な、稼働中のGramps Webインスタンス
• Docker（任意。コンテナーでのデプロイ用）

クイックスタート

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

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

./run-local-server.sh

サーバーは http://127.0.0.1:8080/mcp でHTTPトランスポートを使って起動します。ループバックのみにバインドする場合、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

リフレッシュトークン認証を使用するには、GRAMPS_USERNAME と GRAMPS_PASSWORD の行を -e GRAMPS_REFRESH_TOKEN=your-refresh-token に置き換えます。

公開されている各イメージにはビルド来歴のアテステーションが付属します。これは、イメージのビルドに使用したリポジトリ、ワークフロー、コミットを記録した署名付きの記録で、GitHub とレジストリに保管されています。GitHub CLI を使用すると、このイメージがこのリポジトリの GitHub Actions によってビルドされたことを確認できます（Docker Desktop がインストールされている場合は、先に起動してください。gh はレジストリの認証情報を Docker Desktop に問い合わせます）。

gh attestation verify oci://ghcr.io/scormave/gramps-web-mcp:latest --repo Scormave/gramps-web-mcp

このイメージは、Docker の HEALTHCHECK、Unraid コンテナのヘルスチェック、その他の稼働状況モニター向けに、GET /health エンドポイントを公開します。MCP サーバーが Gramps Web に対して認証できる場合は HTTP 200 を、できない場合は HTTP 503 を返します。プローブではツールと同じトークンを再利用するため、毎回 Gramps Web にログインすることはありません。公開されるレスポンスは最小限で、{ "status": "healthy" } または { "status": "unhealthy" } です。API に到達できるようになると、起動ログに Connected to Gramps Web at … のような行が出力されます。

このイメージは Ubuntu Chiseled をベースとしており、シェルや curl は含まれていません。 HEALTHCHECK は dotnet /app/GrampsWeb.Mcp.dll --health-check を実行し、 ASPNETCORE_URLS で指定されたポートの /health にリクエストを送ります。HTTP 200 の場合は 0 を、それ以外の場合は 1 を終了コードとして返します。Compose や NAS アプリのテンプレートで独自に定義するヘルスチェックでも、同じコマンドを実行します。

healthcheck:
  test: ["CMD", "dotnet", "/app/GrampsWeb.Mcp.dll", "--health-check"]

サーバーが ASPNETCORE_URLS で指定されていないアドレスをリッスンする場合は、オプションの後に URL を渡します。たとえば、--health-check http://localhost:9000 のように指定します。

このイメージは、ポート 8080 で Streamable HTTP（MCP_TRANSPORT=http）をデフォルトで使用します。上記のコマンドではこの設定を使用しています。MCP Registry のインストールなど、コンテナを自分で起動するクライアントは、代わりに -e MCP_TRANSPORT=stdio を指定し、標準入力を開いたままにして（docker run -i）、stdio 経由で実行します。これは 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_TREE_ID、および GRAMPS_USERNAME と GRAMPS_PASSWORD の組み合わせ、または GRAMPS_REFRESH_TOKEN を設定します。 ネットワーク上の他のマシンから MCP ポートにアクセスできる場合は、MCP_API_KEY を設定します。
4. デフォルトのコンテナポート 8080 をそのまま使用するか、別のホストポートに割り当てます。
5. コンテナを起動して /health を確認します。サービスが Gramps Web に認証できるようになると、最小限の JSON レスポンスとともに HTTP 200 が返されます。

最も簡単に接続するには、Gramps Web と gramps-web-mcp を同じ Unraid Docker ネットワークで実行し、GRAMPS_API_URL に Gramps Web コンテナの URL を設定します。クライアント向けの MCP エンドポイントは http://<unraid-host>:<mapped-port>/mcp です。クライアントの接続方法については その他の 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 an authentication method 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から入手できます。 ご利用のプラットフォームに対応するバンドルをダウンロードしてください。

プラットフォーム	成果物
macOS Apple Silicon	gramps-web-mcp-claude-desktop-osx-arm64-v*.mcpb
macOS Intel	gramps-web-mcp-claude-desktop-osx-x64-v*.mcpb
Windows x64	gramps-web-mcp-claude-desktop-win-x64-v*.mcpb
Linux x64	gramps-web-mcp-claude-desktop-linux-x64-v*.mcpb
Linux ARM64	gramps-web-mcp-claude-desktop-linux-arm64-v*.mcpb

1. 最新リリースから、お使いの OS 用の .mcpb ファイルをダウンロードします。
2. ダブルクリックするか、Claude Desktop のウィンドウにドラッグします。
3. Gramps Web の URL、ユーザー名、パスワード／トークン、ツリー UUID を入力します。
4. 最初のセッションでは読み取り専用モードを有効のままにします。Claude にレコードを作成または編集させる場合にのみ、無効にしてください。
5. インストールを完了し、新しいチャットを開始します。

この拡張機能はローカルで stdio 経由で動作するため、お使いのマシンに .NET SDK は必要ありません。ダウンロードしたバンドルがこのリポジトリから提供されたものか確認するには、 リリースバイナリを使った stdio 接続の下にあるアテステーションに関する注記をご覧ください。 パッケージ化の詳細についてはmcpb/README.mdを、プライバシーポリシーについては PRIVACY.mdをご覧ください。

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

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

その他の MCP クライアント

Claude Code、VS Code、Cursor、Codex、Antigravity CLI、 Open WebUI などの他の MCP クライアントは、次の 3 つの方法のいずれかで接続します。

• HTTP 経由：すでにDocker、 Unraidまたは Docker Composeで稼働しているサーバーに接続します。各クライアントに必要なのはサーバーのアドレスと API キーだけで、クライアントのマシンには何もインストールされません。また、すべてのクライアントで 1 台のサーバーを共有します。
• Docker 上の stdio 経由：クライアントがサーバーのイメージを起動します。各マシンに Docker と Gramps Web の認証情報が必要です。VS Code と Cursor では、この設定をワンクリックで追加できます。
• リリースバイナリを使った stdio 経由：クライアントがリリースからダウンロードした単一ファイルを使ってサーバーを起動します。各マシンに Gramps Web の認証情報が必要ですが、Docker も .NET も必要ありません。

Claude Desktop は Anthropic のクラウドから URL で追加されたサーバーに接続するため、お使いのコンピューターからではなく、ホームネットワーク上のサーバーにはアクセスできません。その場合は MCPB 拡張機能を使用してください。

HTTP 経由

サーバーで MCP_API_KEY を設定し（HTTP 認証を参照）、各クライアントにアドレスとキーを伝えます。例では http://192.168.1.10:8080/mcp と your-secret-api-key を使用しています。どちらもご自身の値に置き換えてください。

Claude Code:

claude mcp add --transport http --scope user gramps-web http://192.168.1.10:8080/mcp \
  --header "Authorization: Bearer your-secret-api-key"

VS Code のユーザー用 mcp.json またはワークスペースの .vscode/mcp.json に設定します。VS Code はサーバーの初回起動時にキーを要求します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gramps-web-mcp-key",
      "description": "Gramps Web MCP API key",
      "password": true
    }
  ],
  "servers": {
    "gramps-web": {
      "type": "http",
      "url": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer ${input:gramps-web-mcp-key}" }
    }
  }
}

Cursor の ~/.cursor/mcp.json に設定します。

{
  "mcpServers": {
    "gramps-web": {
      "url": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer your-secret-api-key" }
    }
  }
}

Codex の ~/.codex/config.toml に設定します。Codex は bearer_token_env_var で指定された環境変数からキーを読み込むため、起動前に GRAMPS_WEB_MCP_KEY を設定してください。

[mcp_servers.gramps-web]
url = "http://192.168.1.10:8080/mcp"
bearer_token_env_var = "GRAMPS_WEB_MCP_KEY"

Antigravity CLI の ~/.gemini/config/mcp_config.json に設定します。Gemini CLI では、同じエントリーを ~/.gemini/settings.json に設定し、serverUrl の代わりに httpUrl を使用します。

{
  "mcpServers": {
    "gramps-web": {
      "serverUrl": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer your-secret-api-key" }
    }
  }
}

Open WebUI 0.6.31 以降の場合：管理者が Settings → Admin → Integrations を開き、External Tool Servers でサーバー URL、認証方式 Bearer、Key に API キーを指定して、接続タイプ MCP (Streamable HTTP) の接続を追加します。Open WebUI は自身のコンテナーから接続するため、そこでの localhost はそのコンテナーを指します。ホストのアドレス、または両方が同じ Docker ネットワークを共有している場合は MCP コンテナー名を使用してください。

次の点にご注意ください。

• 通常の HTTP では、キーとツリーデータは暗号化されずに送信されます。ポートは信頼できるネットワーク内にとどめ、外部から接続する場合はインターネットにポートを公開するのではなく、VPN 経由でそのネットワークに接続してください。
• Cursor と Antigravity CLI のファイルにはキーそのものが保存されるため、プロジェクトのリポジトリに含めないでください。
• すべてのクライアントは、サーバーに設定された Gramps Web アカウントとして動作し、Gramps Web はすべての編集をそのアカウントの操作として記録します。
• デフォルトのステートレス HTTP では、delete_object と undo_change に確認ダイアログを表示できません。削除と取り消しの確認を参照してください。

ターミナルからアドレスとキーを確認するには、initialize リクエストを送信します。キーは X-Api-Key: <key> としても使用できます。

curl -X POST http://192.168.1.10: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}'

Docker で stdio 経由

クライアントはセッションごとにコンテナーを起動し、セッション終了時に削除します。イメージのデフォルトは HTTP のため、MCP_TRANSPORT=stdio が必要です。また、値を指定せずに -e NAME とすると、env の変数がコンテナーに渡されるため、パスワードを docker のコマンドラインに表示せずに済みます。

{
  "mcpServers": {
    "gramps-web": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "GRAMPS_API_URL",
        "-e", "GRAMPS_USERNAME",
        "-e", "GRAMPS_PASSWORD",
        "-e", "GRAMPS_TREE_ID",
        "ghcr.io/scormave/gramps-web-mcp:latest"
      ],
      "env": {
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

この README の先頭にあるインストールボタンを使うと、このエントリーが VS Code または Cursor に追加されます。VS Code はサーバーの初回起動時に Gramps Web のアドレス、ユーザー名、パスワード、ツリー ID を要求し、パスワードはシークレットストレージに保存します。Cursor では上記のプレースホルダーが追加されるため、初回起動前にご自身の値に置き換えてください。 [install-vscode]: https://insiders.vscode.dev/redirect/mcp/install?name=gramps-web&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-api-url%22%2C%22description%22%3A%22Gramps%20Web%20address%2C%20such%20as%20https%3A%2F%2Fyour-gramps.example.com%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-username%22%2C%22description%22%3A%22Gramps%20Web%20user%20name%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-password%22%2C%22description%22%3A%22Gramps%20Web%20password%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-tree-id%22%2C%22description%22%3A%22Gramps%20Web%20tree%20ID%22%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22MCP_TRANSPORT%3Dstdio%22%2C%22-e%22%2C%22GRAMPS_API_URL%22%2C%22-e%22%2C%22GRAMPS_USERNAME%22%2C%22-e%22%2C%22GRAMPS_PASSWORD%22%2C%22-e%22%2C%22GRAMPS_TREE_ID%22%2C%22ghcr.io%2Fscormave%2Fgramps-web-mcp%3Alatest%22%5D%2C%22env%22%3A%7B%22GRAMPS_API_URL%22%3A%22%24%7Binput%3Agramps-web-api-url%7D%22%2C%22GRAMPS_USERNAME%22%3A%22%24%7Binput%3Agramps-web-username%7D%22%2C%22GRAMPS_PASSWORD%22%3A%22%24%7Binput%3Agramps-web-password%7D%22%2C%22GRAMPS_TREE_ID%22%3A%22%24%7Binput%3Agramps-web-tree-id%7D%22%7D%7D [install-vscode-insiders]: https://insiders.vscode.dev/redirect/mcp/install?name=gramps-web&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-api-url%22%2C%22description%22%3A%22Gramps%20Web%20address%2C%20such%20as%20https%3A%2F%2Fyour-gramps.example.com%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-username%22%2C%22description%22%3A%22Gramps%20Web%20user%20name%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-password%22%2C%22description%22%3A%22Gramps%20Web%20password%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-tree-id%22%2C%22description%22%3A%22Gramps%20Web%20tree%20ID%22%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22MCP_TRANSPORT%3Dstdio%22%2C%22-e%22%2C%22GRAMPS_API_URL%22%2C%22-e%22%2C%22GRAMPS_USERNAME%22%2C%22-e%22%2C%22GRAMPS_PASSWORD%22%2C%22-e%22%2C%22GRAMPS_TREE_ID%22%2C%22ghcr.io%2Fscormave%2Fgramps-web-mcp%3Alatest%22%5D%2C%22env%22%3A%7B%22GRAMPS_API_URL%22%3A%22%24%7Binput%3Agramps-web-api-url%7D%22%2C%22GRAMPS_USERNAME%22%3A%22%24%7Binput%3Agramps-web-username%7D%22%2C%22GRAMPS_PASSWORD%22%3A%22%24%7Binput%3Agramps-web-password%7D%22%2C%22GRAMPS_TREE_ID%22%3A%22%24%7Binput%3Agramps-web-tree-id%7D%22%7D%7D&quality=insiders [install-cursor]: https://cursor.com/en/install-mcp?name=gramps-web&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItZSIsIk1DUF9UUkFOU1BPUlQ9c3RkaW8iLCItZSIsIkdSQU1QU19BUElfVVJMIiwiLWUiLCJHUkFNUFNfVVNFUk5BTUUiLCItZSIsIkdSQU1QU19QQVNTV09SRCIsIi1lIiwiR1JBTVBTX1RSRUVfSUQiLCJnaGNyLmlvL3Njb3JtYXZlL2dyYW1wcy13ZWItbWNwOmxhdGVzdCJdLCJlbnYiOnsiR1JBTVBTX0FQSV9VUkwiOiJodHRwczovL3lvdXItZ3JhbXBzLmV4YW1wbGUuY29tIiwiR1JBTVBTX1VTRVJOQU1FIjoieW91ci11c2VyIiwiR1JBTVBTX1BBU1NXT1JEIjoieW91ci1wYXNzd29yZCIsIkdSQU1QU19UUkVFX0lEIjoieW91ci10cmVlLXV1aWQifX0%3D

• Cursor（~/.cursor/mcp.json）、Antigravity CLI （~/.gemini/config/mcp_config.json）、Gemini CLI （~/.gemini/settings.json）では、このエントリーをそのまま使用します。
• Claude Code：gramps-web オブジェクトを claude mcp add-json --scope user gramps-web '<object>' に渡します。
• VS Code：エントリーを mcpServers ではなく servers の下に配置し、 "type": "stdio" を追加します。
• Codex：同じ command、args、env を ~/.codex/config.toml の [mcp_servers.gramps-web] の下に配置します。
• Open WebUI は HTTP のみで接続します。

初回起動の前に：

• イメージを一度、docker pull ghcr.io/scormave/gramps-web-mcp:latestで取得します。 クライアントによってはサーバーの起動を数秒しか待たないため、ダウンロードには時間が足りません。
• コンテナ内のlocalhostはコンテナ自体を指します。Gramps Webが同じコンピューター上で動作している場合は、GRAMPS_API_URLでhost.docker.internalを使用します。Linuxでは、argsにも"--add-host=host.docker.internal:host-gateway"を追加してください。
• リフレッシュトークンを使用するには、両方のリストでGRAMPS_USERNAMEとGRAMPS_PASSWORDをGRAMPS_REFRESH_TOKENに置き換えます。読み取り専用モードにするには、イメージ名の前に"-e", "GRAMPS_READ_ONLY=true"を追加します。ほかの設定も同様に指定します。
• アップロードではコンテナ内のファイルを読み取るため、-vでアップロードフォルダーをマウントします。

stdio 経由でリリースバイナリを使用する

各リリースには、Claude Desktopのバンドルに含まれているものと同じ、サーバーの自己完結型ファイルも含まれています。特に指定しない限り、stdio 経由で起動します。

プラットフォーム	アーカイブ
macOS Apple Silicon	gramps-web-mcp-osx-arm64.tar.gz
macOS Intel	gramps-web-mcp-osx-x64.tar.gz
Windows x64	gramps-web-mcp-win-x64.zip
Linux x64	gramps-web-mcp-linux-x64.tar.gz
Linux ARM64	gramps-web-mcp-linux-arm64.tar.gz

使用するプラットフォームのアーカイブを展開し、専用のフォルダーに入れます。macOSまたはLinuxの場合（ここではApple Siliconを例にしています。お使いの環境に合わせてアーカイブ名を変更してください）：

mkdir -p ~/.local/share/gramps-web-mcp
curl -fL https://github.com/Scormave/gramps-web-mcp/releases/latest/download/gramps-web-mcp-osx-arm64.tar.gz \
  | tar -xz -C ~/.local/share/gramps-web-mcp

Windowsの場合は、PowerShellで実行します。

curl.exe -fLo "$env:TEMP\gramps-web-mcp.zip" https://github.com/Scormave/gramps-web-mcp/releases/latest/download/gramps-web-mcp-win-x64.zip
Expand-Archive -Force "$env:TEMP\gramps-web-mcp.zip" "$env:LOCALAPPDATA\gramps-web-mcp"

クライアントは~を展開するシェルを介さずにバイナリを起動するため、バイナリのフルパスを指定してクライアントから参照します。

{
  "mcpServers": {
    "gramps-web": {
      "command": "/Users/you/.local/share/gramps-web-mcp/GrampsWeb.Mcp",
      "env": {
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

Windowsでは、commandは "C:\\Users\\you\\AppData\\Local\\gramps-web-mcp\\GrampsWeb.Mcp.exe"です。JSONでは、各バックスラッシュを2つ重ねる必要があります。各クライアントでは、上記のDockerの設定と同じ要領でこの項目を指定します。

• すべての設定は、env内の環境変数として指定します。たとえば、ユーザー名とパスワードの代わりにGRAMPS_REFRESH_TOKENを使用したり、"GRAMPS_READ_ONLY": "true"と指定したりします。Dockerとは異なり、GRAMPS_API_URL内のlocalhostとアップロードフォルダーは、お使いのコンピューター上のものになります。
• 更新するには、クライアントを終了し（Windowsでは実行中のバイナリを置き換えられません）、同じコマンドを再度実行してからクライアントを起動します。アーカイブ名にバージョンが含まれていないため、リンクから常に最新のリリースを取得でき、新しいバイナリが古いものに置き換わります。
• このバイナリはAppleによる公証を受けていません。curlでダウンロードした場合、ダウンロード済みのマークが付かないためmacOSで実行できます。ブラウザーでアーカイブをダウンロードした場合、xattr -d com.apple.quarantine ~/.local/share/gramps-web-mcp/GrampsWeb.Mcpでマークを削除するまで、macOSがバイナリの起動を拒否することがあります。
• LinuxではglibcとICU（libicu）が必要です。デスクトップ向けディストリビューションには含まれています。Alpineまたは最小構成のシステムでは、Dockerを使用してください。
• 各リリースのSHA256SUMSには、含まれるファイルのチェックサムが記載されています。また、バンドルを含むすべてのファイルには、ビルド来歴のアテステーションが付与されています。ダウンロードを確認するには、アーカイブをtarにパイプせずに保存し、GitHub CLIでgh attestation verify gramps-web-mcp-osx-arm64.tar.gz --repo Scormave/gramps-web-mcpを実行します。このリポジトリのリリースワークフローでそのファイルがビルドされていない場合、検証は失敗します。

この同じバイナリで、イメージと同じようにHTTP経由でほかのマシンにもサービスを提供できます。詳しくはトランスポートを参照してください。ソースをチェックアウトしてサーバーを実行する方法については、開発者ガイドのローカル開発を参照してください。

視覚対応エージェント向けの画像

視覚対応エージェントは、read_media または gramps://media/{handle}/thumbnail/{size} や gramps://media/{handle}/file などのバイナリ MCP リソースを通じて、オプトインしたメディアを読み取れます。 read_media のデフォルトはサムネイルです。サーバーがオリジナルから生成する JPEG プレビュー（画像に透明部分がある場合は PNG）で、長辺は 1568 ピクセルです。 そのため、文書のスキャン画像にある手書きや小さな文字も読みやすく保たれます。小さめまたは 大きめのプレビューを取得するには size（1～4096）を指定します。画像が拡大されることはありません。プレビューは ピクセルから再エンコードされるため、EXIF（GPS を含む）、XMP、IPTC、ICC のメタデータは 送信されません。JPEG、PNG、GIF、WebP、BMP、TIFF、TGA、PBM、QOI のオリジナルから プレビューを生成できます。複数ページのファイルでは最初のページが使われます。PDF などの画像以外の メディア、および AVIF、HEIC/HEIF、JPEG XL、SVG 画像にはプレビューがありません。オリジナルファイルを使うには mode: "file" を指定し、size は省略してください。 ファイルモードでは MIME タイプに応じて、画像、音声、または埋め込み blob リソースのコンテンツが返されます。TIFF など、MCP クライアントが表示できない画像は、サムネイルを使うよう促すヒント付きの埋め込み blob として返されます。エンドツーエンドの分析には、 MCP クライアントが型付きツールコンテンツまたはバイナリリソースコンテンツを、対応するモデルに転送する必要があります。

設定

Gramps 接続

変数	説明
GRAMPS_API_URL	Gramps Web インスタンスのベース URL（末尾のスラッシュなし）
GRAMPS_USERNAME	API ユーザー名
GRAMPS_PASSWORD	API パスワード
GRAMPS_TREE_ID	そのサーバー上のツリー UUID

パスワードの代わりに更新トークンを使う

Gramps Web でパスワードによるログインが無効になっている場合（OIDC_DISABLE_LOCAL_AUTH=true）は、 GRAMPS_REFRESH_TOKEN を設定し、GRAMPS_USERNAME と GRAMPS_PASSWORD は 未設定のままにしてください。サーバーはこれを /api/token/refresh/ でアクセス トークンに交換します。

パスワードによるログインがまだ有効な間に取得してください。

curl -s -X POST https://gramps.example.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"mcp","password":"..."}' | jq -r .refresh_token

Gramps Web の更新トークンは有効期限がありません。パスワードと同様に扱ってください。ユーザーを削除するか、 Gramps Web の秘密鍵をローテーションすると無効になります。

実行モード

変数	デフォルト
GRAMPS_READ_ONLY	false
GRAMPS_MUTATION_SERIALIZE	true
GRAMPS_MUTATION_MIN_INTERVAL_MS	0

• 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 クライアント間では調整されません。
• 順次編集を行っても SQLite 環境で database is locked が発生する場合は、 GRAMPS_MUTATION_MIN_INTERVAL_MS=250 または 500 を設定してください。
• SQLite のロックエラーまたは上流からの HTTP 429 が発生した場合、変更ツールは一般的な 500 エラーではなく、短いバックオフ時間のヒントを含む再試行可能な MCP エラーを返します。
• Gramps Web が PostgreSQL を使用していて、並列書き込みを行いたい場合は GRAMPS_MUTATION_SERIALIZE=false を設定してください。

削除と取り消しの確認

クライアントがMCP elicitationに対応している場合、delete_object と undo_change はツリーを変更する前にダイアログでユーザーに確認します。ダイアログにはレコードの名前、または取り消しによって変更される内容が表示され、続行するにはユーザーがチェックボックスにチェックを入れます。拒否するかダイアログを閉じると、何も変更されません。ドライランと拒否の場合は確認を求めません。

変数	説明	デフォルト
GRAMPS_CONFIRMATION	when-supported はエリシテーションに対応するクライアントに確認を求め、それ以外のクライアントでは従来どおり動作します。required は確認できないクライアントでの削除と取り消しを拒否します。off は確認を求めません	when-supported

• ステートレス Streamable HTTP（デフォルトの MCP_STATELESS=true）ではクライアントにリクエストを送信できないため、確認を求めません。また、ここでは required によってすべての削除と取り消しが拒否されます。HTTP 経由で確認するには MCP_STATELESS=false を設定してください。stdio と従来の SSE はセッションを維持できるため、確認を求められます。
• どちらのツールにも、設定にかかわらず anthropic/requiresUserInteraction ツールメタデータが付与されます。Claude Code など、これを尊重するクライアントは独自に先に許可を求めるため、ユーザーが2回確認する場合があります。off にすると、クライアント側のプロンプトだけが表示されます。
• ツールの呼び出しは、ユーザーが回答するまで続きます。クライアントが先に呼び出しをキャンセルした場合、何も変更されません。
• サーバーは、確認を求めるかどうかをクライアントごとに一度ログに記録します。

ダイアログと応答については、ツールカタログを参照してください。

リンクされたレコードの更新

リンクリストを受け取る9つの update_* ツールには、linkMode 引数があります。値は replace（デフォルト）、add、remove です。たとえば、update_person(handle: "PERSON_HANDLE", noteHandles: ["NOTE_HANDLE"], linkMode: "add") は、人物の既存のメモリストをコピーせずにメモを追加します。remove には、リンクを解除するハンドルを指定します。リストを省略すると変更されません。[] によってリストがクリアされるのは replace モードの場合のみです。このモードは、呼び出しで指定されたすべてのリンクリストに適用されます。add では既存のリンクメタデータが保持されます。メタデータを変更するには replace を使用してください。対応するリストと同時実行の制限については、ツールカタログを参照してください。

2.3.1 より前の更新で失われたデータ

2.3.1 より前のバージョンでは、update_* ツールが呼び出しで指定されていない保存済みデータを削除することがありました（#5）。以前のバージョンでツリーを編集した場合、scripts/find-update-losses.py は Gramps Web のトランザクション履歴を読み取り、更新によって値が消去された項目をすべて、消去前の値とレコードにまだ値がないかどうかとともに一覧表示します。

GRAMPS_API_URL=https://gramps.example.com GRAMPS_USERNAME=me GRAMPS_PASSWORD=... \
  python3 scripts/find-update-losses.py --user MCP_ACCOUNT --until 2026-10-07 --json losses.json

Python 3.9 以降と、非公開レコードを閲覧できるアカウントが必要です。また、読み取りのみを行います。履歴には Gramps Web インターフェースで行った編集も含まれます。また、意図的に消去した値と削除された値は同じように表示されるため、復元する前に各項目を確認してください。

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

メディアのバイトデータを扱うツール／リソースは、デフォルトで無効です。objectType: "media" を指定した get_object は、ファイルのダウンロードを有効にしなくても、メタデータの取得に引き続き利用できます。 無効の場合、tools/list から read_media が除外されます。名前をすでに知っているクライアントが直接呼び出すと、バイトデータをダウンロードせずに設定エラーが返されます。同じ設定でアップロードの有効／無効も切り替わります。

変数	説明	デフォルト
GRAMPS_MEDIA_RESOURCES_ENABLED	サムネイルとファイル全体を扱うバイナリメディアツール／リソース、およびアップロードを有効にします	false
GRAMPS_MEDIA_MAX_BYTES	read_media または任意のメディアリソースが返す最大バイト数	5242880
GRAMPS_MEDIA_ALLOW_PRIVATE	非公開に設定された Gramps メディアレコードのバイトデータを許可します	false

AI による分析には、read_media(mode: "thumbnail") または gramps://media/{handle}/thumbnail/{size} を優先してください。ファイル全体はサイズが大きく機密情報を含む可能性があり、元のメタデータも保持されます。また、サイズと非公開レコードのチェックが引き続き適用されます。

GRAMPS_MEDIA_MAX_BYTES はクライアントに返すデータを制限します。サムネイルを生成するため、サーバーは Gramps Web からオリジナルをメモリにダウンロードします。上限は 50 MiB または GRAMPS_MEDIA_MAX_BYTES の大きいほうまで、かつ 1 億画素までです。返されるのはプレビューのみです。

GRAMPS_MEDIA_ALLOWED_MIME_TYPES は使用されなくなりました。設定から削除してください。サーバーはこの変数を無視し、設定されている場合は起動時に警告をログに記録します。

メディアのアップロード

create_media は、サーバー上のフォルダーから写真、書類のスキャン画像、または PDF をアップロードし、attachTo で指定されたレコードに表示します。update_media では filePath を指定して、レコードのファイルを置き換えます。アップロードにはメディアファイルへのアクセス（GRAMPS_MEDIA_RESOURCES_ENABLED=true）と、GRAMPS_MEDIA_UPLOAD_DIRS に指定されたフォルダーが少なくとも 1 つ必要です。両方が設定されるまでは、create_media は表示されません。これらのフォルダー内のファイルのみ読み取り可能で、シンボリックリンクも対象です。内容に基づいて判定される JPEG、PNG、GIF、WebP、TIFF、BMP、PDF ファイルのみが対象です。ツリーにすでに保存されているファイルは再利用され、二重にアップロードされません。Docker では、フォルダーをコンテナーにマウントし、コンテナー内から見えるパスを設定してください。

変数	説明	デフォルト
GRAMPS_MEDIA_UPLOAD_DIRS	create_media と update_media がアップロード元として使用できる、:（Windows では ;）区切りの絶対パス	未設定（無効）
GRAMPS_MEDIA_UPLOAD_MAX_BYTES	create_media または update_media がアップロードできるファイルの最大サイズ	52428800

トランスポート

上記の説明に従って、GRAMPS_API_URL、GRAMPS_TREE_ID と、ユーザー名／パスワードのペアまたは GRAMPS_REFRESH_TOKEN を設定してください。

値	動作
(未設定または stdio)	標準入力／標準出力を介した JSON-RPC（デフォルト。ローカルクライアント向け）。
http	MCP_PATH（デフォルトは /mcp）で Streamable HTTP を使用します。
sse	レガシー MCP SSE：GET {MCP_PATH}/sse + POST {MCP_PATH}/message。ステートフルです。古いクライアントでのみ使用してください。

HTTP トランスポートでは、レスポンスは SSE でストリーミングされます。プロトコルの詳細については、Streamable HTTP の仕様を参照してください。待ち受けアドレスを選択するには、たとえば http://127.0.0.1:8080 のように ASPNETCORE_URLS を設定します。

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

変数	説明	デフォルト
ASPNETCORE_URLS	HTTP/SSE の待ち受け URL	—
MCP_PATH	MCP エンドポイントの URL プレフィックス	/mcp
MCP_STATELESS	Streamable HTTP のステートレスモード	true
MCP_ENABLE_LEGACY_SSE	http トランスポートでレガシー /sse を公開します	false
MCP_API_KEY	HTTP/SSE トランスポート用の共有シークレット（ローテーション時はカンマ区切り。16 文字以上）	—
MCP_ALLOWED_ORIGINS	HTTP/SSE エンドポイントの呼び出しを許可するブラウザーのオリジン（カンマ区切り）。それ以外のオリジンからのリクエストには 403 が返されます	—

HTTP 認証

MCP_API_KEY が設定されている場合、すべての MCP HTTP/SSE エンドポイントでは、各リクエストでキーが必要です。Docker とロードバランサーのプローブ用に、GET /health は引き続き匿名でアクセスできます。

キーを生成します。

openssl rand -base64 32

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

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

ブラウザーのオリジン

ブラウザーはリクエストに Origin ヘッダーを付けて送信します。サーバーは、オリジンが MCP_ALLOWED_ORIGINS に記載されていないすべてのリクエストを 403 で拒否します。これにより、別のサイト上のウェブページがサーバーの Gramps 認証情報を使ってツールを呼び出すことを防ぎます。これは DNS リバインディング経由の呼び出しにも有効で、サーバーが 127.0.0.1 のみで待ち受けている場合でも機能します。Claude Desktop、Claude Code、SDK クライアントなど、ブラウザー以外の MCP クライアントは Origin を送信しないため、設定は不要です。信頼できるブラウザーベースの MCP クライアントを使用する場合は、そのオリジンを指定します。

MCP_ALLOWED_ORIGINS=https://app.example.com

SECURITY.md では、Host ヘッダーに対する任意の AllowedHosts チェックについても説明しています。

ログ

変数	説明	デフォルト
GRAMPS_LOG_LEVEL	サーバー独自のメッセージのログレベル：Trace、Debug、Information、Warning、Error、Critical、None	Information

ログは標準エラー出力に書き込まれます。Claude Desktop はログをローカルファイルに保存します（macOS では ~/Library/Logs/Claude/mcp-server-Gramps Web MCP.log）。

Information では、Gramps API の各呼び出しについて、メソッド、パス（クエリ文字列を除く）、ステータス、処理時間、本文の長さがログに記録されます。メディアのダウンロードでは、本文の長さの代わりにコンテンツタイプと長さが記録されます。リクエストとレスポンスの本文および完全な URL には、系譜データ（名前、日付、検索語句）が含まれるため、ログに記録されるのは Debug または Trace の場合のみです。その場合でも、認証情報と思われるフィールドは秘匿されます。トラブルシューティング中のみ Debug を使用し、その後ログファイルを削除してください。

開発

dotnet test

CONTRIBUTING.md と開発者ガイドをご覧ください。

ドキュメント

ドキュメント	説明
ドキュメント一覧	すべてのドキュメントファイル
ツールカタログ	MCP ツールの完全なリファレンス
Claude Desktop MCPB	デスクトップ拡張機能のパッケージ化
プライバシーポリシー	デスクトップ拡張機能におけるデータの取り扱い
システムプロンプト	MCP クライアント向けの推奨プロンプト
アーキテクチャ	システム設計の概要

コントリビューション

コントリビューションを歓迎します。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）の下でライセンスされています。これはネットワークサーバーソフトウェアであるため、改変版をホストする場合、ネットワーク経由で利用するユーザーが対応するソースコードを入手できるようにする必要があります。

ImageSharp、MCP C# SDK、.NET ランタイムなど、同梱されるサードパーティコンポーネントには、それぞれ Apache 2.0 または MIT ライセンスが適用されます。詳細は THIRD-PARTY-NOTICES.txtをご覧ください。MCP Bundles と Docker イメージには、このファイルが LICENSE とともに同梱されています。