GeoGuessrMCP

たんさく

Geoguessrmcp

GeoGuessrゲームの統計データを分析するためのMCPサーバーです。多ユーザーの独立したセッションと動的API監視をサポートし、APIの変更に自動的に適応し、包括的なゲームデータ分析機能を提供します。

ゲームとゲーム化研究とデータ #ゲーム分析 #多ユーザー #動的監視 #API適合 .Python

スコア : 2ポイント

ダウンロード数 : 5.2K

更新時間 : 2025-12-03

サイトを開く

GeoGuessr MCP Serverとは？

GeoGuessr MCP Serverは、Claude AIとGeoGuessrゲームデータをつなぐスマートな架け橋です。自然言語での会話を通じて、ゲームの統計データ、履歴、実績、パフォーマンストレンドを照会・分析することができます。サーバーは自動的にGeoGuessr APIの変更を監視し、常に最新のデータを取得できるようにします。

GeoGuessr MCP Serverの使い方は？

使い方はとても簡単です。1) サーバー上にMCPサービスをデプロイします。2) Claude Desktopで接続を設定します。3) GeoGuessrアカウントにログインします。4) 会話を通じてデータを照会し始めます。「最近のゲームパフォーマンスを表示」や「弱点を分析」などの質問をClaudeに直接投げかけることができます。

適用シーン

すべてのGeoGuessrプレイヤーに適しています。特に、自分のゲームパフォーマンスを深く理解したいプレイヤー、改善策を見つけたい競技プレイヤー、進歩傾向を追跡したい日常的なプレイヤー、そして友人と統計データを共有したい社交的なプレイヤーに最適です。

主要機能

多ユーザーサポート

複数のユーザーが同時に同じサーバーを利用できます。各ユーザーは自分のGeoGuessrアカウントにログインでき、データは完全に分離されています。家族や友人はサーバーを共有しても互いに干渉することはありません。

動的API監視

GeoGuessr APIの変更を自動的に検出し、APIが更新された場合、サーバーは自動的に適応します。手動でコードを更新する必要はありません。すべてのインターフェースを毎日自動的にチェックし、データ取得の安定性を確保します。

包括的なデータ分析

完全なゲームデータ分析を提供します。個人プロフィール、ゲーム履歴、詳細な統計、実績追跡、パフォーマンストレンド、マップ固有のパフォーマンスなどが含まれます。ゲーム習慣を深く理解するのに役立ちます。

戦略提案

ゲームデータに基づいて、個別の改善提案を提供します。例えば、特定の地域での弱点を特定し、練習するマップの種類を提案したり、ゲーム戦略を最適化したりします。

簡易デプロイ

Dockerによるワンクリックデプロイ方案を提供し、開発環境と本番環境の両方をサポートします。事前に構築されたDockerイメージにより、複雑な設定プロセスを必要とせずに、簡単かつ迅速にデプロイできます。

安全な認証

二重認証をサポートします。MCPサーバーのアクセス制御とGeoGuessrアカウントのログインです。データとアクセス権限が十分に保護されます。

利点

APIを手動で照会する必要がない：自然言語での会話を通じてすべてのデータを取得できます

変更に自動的に適応する：APIが更新された場合、サーバーは自動的に調整され、メンテナンスの必要性が減少します

多ユーザーに優しい：家族や小さなチームが1つのサーバーインスタンスを共有できます

深い分析：公式よりも詳細な統計とトレンド分析を提供します

統合が容易：Claude AIとシームレスに統合され、使い勝手が良い

制限

サーバーのデプロイが必要：基本的なVPSまたはクラウドサーバーの知識が必要です

サードパーティAPIに依存する：GeoGuessr APIの安定性とレート制限の影響を受けます

Claudeのサブスクリプションが必要：Claude Desktopを使用して接続する必要があります

非公式ツール：GeoGuessr公式で開発されていないため、機能が制限される可能性があります

学習曲線：初回の設定にはいくつかの技術的な操作が必要です

使い方

サーバーをデプロイする

VPSまたはローカルサーバー上にMCPサービスをデプロイします。Dockerを使用したワンクリックデプロイが可能で、さまざまな環境設定をサポートします。

Claude Desktopを設定する

Claude Desktopの設定ファイルにMCPサーバーの接続情報を追加します。サーバーアドレスと認証キー（有効にした場合）を指定する必要があります。

GeoGuessrアカウントにログインする

Claudeでの会話を通じてGeoGuessrアカウントにログインします。メールアドレスとパスワードでログインするか、認証クッキーを手動で設定することができます。

データ照会を開始する

これで、自然言語での会話を通じてゲームデータを照会・分析できます。Claudeがあなたのリクエストを理解し、対応する統計データを返します。

使用例

日常のパフォーマンスチェック

プレイヤーが当日のゲームパフォーマンスをすぐに把握し、改善の余地があるかどうかを確認したい場合。

弱点分析

競技プレイヤーが特定の地域での弱点を見つけ、ターゲットとした練習を行いたい場合。

進捗追跡

プレイヤーが1か月間の進歩状況を追跡し、レベルアップとスキルの向上を確認したい場合。

社交的な比較

友人同士がゲームデータを比較し、互いの強みと弱みを把握したい場合。

よくある質問

このサービスを利用するには料金がかかりますか？

私のGeoGuessrパスワードは安全ですか？

複数人が同時に利用できますか？

GeoGuessrがAPIを更新した場合はどうなりますか？

デプロイにはどれくらいの技術知識が必要ですか？

データの更新頻度はどれくらいですか？

モバイルデバイスに対応していますか？

サーバーがダウンした場合はどうなりますか？

🚀 GeoGuessr MCP Server

GeoGuessrのゲーム統計を分析するためのModel Context Protocol (MCP)サーバーです。自動API監視と動的スキーマ適応機能を備えています。

TODO

[x] ~~composeファイルと環境変数のDockerユーザー名を修正する~~
[x] ~~MCPサーバーに認証を追加し、特定のユーザーのみがアクセスできるようにする~~
[ ] テストが実行されない問題のコード品質を修正する
[ ] blackがフォーマットしない問題のコード品質を修正する
[ ] 新しいエンドポイントの自動監視を追加し、メールで通知を送信する

✨ 主な機能

マルチユーザー対応

独立したセッション：各APIキーには独自のGeoGuessrセッションが割り当てられます。
複数アカウント：異なるユーザーが自分のGeoGuessrアカウントにアクセスできます。
単一サーバー：ユーザーごとに別々のインスタンスをデプロイする必要はありません。
自動コンテキスト：ユーザーセッションはリクエストごとに自動的に管理されます。

動的API監視

自動エンドポイント検出：GeoGuessr APIエンドポイントを毎日監視します。
スキーマ変更検出：APIレスポンス形式が変更されたときに自動的に検出します。
自己適応：実際のAPIレスポンスに基づいて内部データモデルを更新します。
ハードコードされた仮定なし：GeoGuessrがAPIを変更しても機能します。

包括的な分析

プロファイルと統計情報の取得
ゲーム履歴とラウンドごとの分析
パフォーマンス追跡とトレンド検出
ゲームプレイパターンに基づく戦略推奨

簡単なデプロイ

Docker Composeを使用した簡単なVPSデプロイ
nginxとSSLサポートを備えた本番環境対応
再起動間での永続的なスキーマキャッシュ

🚀 クイックスタート

前提条件

DockerとDocker Compose
GeoGuessrアカウント

1. クローンと設定

git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP
cp .env.example .env

2. デプロイ

docker compose up -d --build

以上で完了です！サーバーがポート8000で起動しました。

3. MCPサーバー認証の設定（オプション）

APIキー認証でMCPサーバーをセキュアにするには、.envを編集します。

MCP_AUTH_ENABLED=true
MCP_API_KEYS=your-secure-api-key-here

安全なAPIキーを生成します。

openssl rand -hex 32

4. Claudeに接続する

Claude Desktopの設定に追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

認証なし:

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp"
    }
  }
}

認証あり:

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "http://YOUR_VPS_IP:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-api-key-here"
      }
    }
  }
}

🔐 認証

サーバーはマルチユーザー対応の2種類の認証をサポートしています。

MCPサーバー認証（MCPサーバーへのアクセスを制御）

MCPサーバーに接続できるユーザーを制限します。有効にすると、クライアントは有効なAPIキーを提供する必要があります。

マルチユーザー対応: 各APIキーには独自のGeoGuessrセッションが割り当てられ、複数のユーザーが同じMCPサーバーインスタンスを自分のアカウントで使用できます！

.envで有効にする:

MCP_AUTH_ENABLED=true
MCP_API_KEYS=key1,key2,key3  # 複数ユーザーの場合はカンマ区切り

安全なキーを生成する:

openssl rand -hex 32

認証付きでClaude Desktopを設定する:

{
  "mcpServers": {
    "geoguessr": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

マルチユーザーの例:

# 各ユーザーに独自のAPIキーを付与
MCP_API_KEYS=alice_key_abc123,bob_key_def456,charlie_key_ghi789

# AliceはAuthorization: Bearer alice_key_abc123で接続
# BobはAuthorization: Bearer bob_key_def456で接続
# それぞれが自分のGeoGuessrアカウントにログインできます！

GeoGuessr API認証（GeoGuessrデータへのアクセス）

サーバーはGeoGuessrのAPIにアクセスするための認証も必要です。マルチユーザーモードでは、各APIキーの所有者は自分のGeoGuessrアカウントにログインできます。

オプション1: Claudeを介してログインする（推奨）

Claudeに次のように依頼します。

"メールアドレス: myemail@example.com とパスワード: mypassword でGeoGuessrにログインする"

オプション2: 環境変数

.envファイルに追加します。

GEOGUESSR_NCFA_COOKIE=your_cookie_value_here

オプション3: 手動でクッキーを設定する

ブラウザから抽出したクッキーを使用して、set_ncfa_cookieツールを使用します。

👥 マルチユーザーモード

サーバーは、単一のMCPサーバーインスタンスを使用して、複数のユーザーがそれぞれ独自のGeoGuessrアカウントを使用できるようになっています。

動作原理

APIキー：各ユーザーに一意のAPIキーが割り当てられます。
独立したセッション：各APIキーには独自のGeoGuessrログインセッションがあります。
自動ルーティング：サーバーはリクエストを自動的に正しいユーザーのセッションにルーティングします。
干渉なし：ユーザーは互いのセッションに影響を与えません。

セットアップ例

1. 複数のAPIキーを設定する

# .envファイル
MCP_AUTH_ENABLED=true
MCP_API_KEYS=alice_key,bob_key,charlie_key

2. サーバーを再起動する

# 開発環境
docker compose restart

# 本番環境
docker compose -f docker-compose.prod.yml restart

3. 各ユーザーが接続する

// AliceのClaude Desktop設定
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer alice_key"}
    }
  }
}

// BobのClaude Desktop設定
{
  "mcpServers": {
    "geoguessr": {
      "url": "https://your-domain.com/mcp",
      "headers": {"Authorization": "Bearer bob_key"}
    }
  }
}

4. 各ユーザーがログインする

AliceはClaudeに "自分の資格情報でGeoGuessrにログインする" と依頼します。
BobはClaudeに "自分の資格情報でGeoGuessrにログインする" と依頼します。
セッションは完全に独立しています！

新しいユーザーの追加

既存のデプロイに新しいユーザーを追加するには、以下の手順を実行します。

.envを編集し、MCP_API_KEYSに新しいAPIキーを追加します。
サーバーを再起動します。docker compose restart
新しいAPIキーをユーザーに共有します。
ユーザーはClaude DesktopにAPIキーを設定します。
ユーザーはClaudeを介して自分のGeoGuessrアカウントにログインします。

サーバーは約2 - 3秒で再起動し、すべての既存のユーザーはログインしたままです！

📊 利用可能なツール

認証

ツール	説明
`login`	メールアドレスとパスワードで認証する
`logout`	現在のセッションを終了する
`set_ncfa_cookie`	認証クッキーを手動で設定する
`get_auth_status`	認証ステータスを確認する

プロファイルと統計情報

ツール	説明
`get_my_profile`	自分のプロファイル情報を取得する
`get_my_stats`	自分のゲーム統計情報を取得する
`get_extended_stats`	追加の統計情報を取得する
`get_achievements`	自分の実績を取得する
`get_comprehensive_profile`	統合されたプロファイルデータを取得する

ゲームとアクティビティ

ツール	説明
`get_activity_feed`	最近のアクティビティを取得する
`get_recent_games`	最近のゲームの詳細を取得する
`get_game_details`	特定のゲームの情報を取得する
`get_season_stats`	競技シーズンの統計情報を取得する
`get_daily_challenge`	日次チャレンジの情報を取得する

分析

ツール	説明
`analyze_recent_games`	パフォーマンストレンドを分析する
`get_performance_summary`	包括的なパフォーマンス概要を取得する
`get_strategy_recommendations`	パーソナライズされた改善ヒントを取得する

API監視

ツール	説明
`check_api_status`	すべてのエンドポイントの可用性を確認する
`get_endpoint_schema`	特定のエンドポイントのスキーマを取得する
`list_available_endpoints`	すべての既知のエンドポイントをリストする
`explore_endpoint`	新しいAPIエンドポイントを探索する

🔄 動的スキーマシステム

サーバーはAPIの変更に自動的に適応します。

┌─────────────────────┐      ┌──────────────────┐
│   API Response      │ ───▶ │  Schema Detector │
└─────────────────────┘      └────────┬─────────┘
                                      │
                                      ▼
┌─────────────────────┐      ┌──────────────────┐
│  Schema Registry    │ ◀─── │  Compare Hash    │
│  (Persisted)        │      └──────────────────┘
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│  Dynamic Response   │ ───▶ Available to LLM
│  with Schema Info   │
└─────────────────────┘

動作原理

毎日の監視：サーバーはすべての既知のエンドポイントを24時間ごとにチェックします。
スキーマ検出：レスポンス構造、フィールドタイプ、およびネストを分析します。
変更検出：スキーマハッシュを計算して変更を検出します。
永続化：スキーマはディスクにキャッシュされ、再起動後も保持されます。
動的アクセス：ツールはLLMにスキーマ情報を含むデータを返します。

例: 未知のエンドポイントの探索

ユーザー: "Can you explore the /v3/some-new-endpoint API?"

Claudeはexplore_endpointツールを使用します。
{
  "success": true,
  "discovered_fields": ["id", "name", "data", "timestamp"],
  "schema_description": "Endpoint: /v3/some-new-endpoint\nFields:\n  - id: string\n  - name: string\n  - data: object\n  - timestamp: datetime"
}

🏭 本番環境デプロイ

サーバーは事前構築されたDockerイメージとして利用可能です。nyxiumyuuki/geoguessr-mcp:latest

方法1: スクリプトを使用した迅速なデプロイ

既存のnginx-proxy-managerを使用したVPSデプロイの場合。

# VPS上でリポジトリをクローンする
git clone https://github.com/NyxiumYuuki/GeoGuessrMCP.git
cd GeoGuessrMCP

# 環境を設定する
cp .env.example .env
# .envを自分の設定で編集する
# - GEOGUESSR_NCFA_COOKIE (GeoGuessr APIアクセス用)
# - MCP_AUTH_ENABLED=true (オプション、MCPサーバーのセキュリティ用)
# - MCP_API_KEYS (認証が有効な場合)

# デプロイスクリプトを実行する
./scripts/deploy.sh

方法2: 手動でDocker Composeを使用したデプロイ

開発/テスト設定

# docker-compose.yml (開発用) を使用する
docker compose up -d

nginx-proxy-managerを使用した本番環境設定

# docker-compose.prod.yml (本番用) を使用する
docker compose -f docker-compose.prod.yml up -d

nginx-proxy-managerでSSLを設定する:

管理パネルにアクセスする: http://your-vps-ip:81
ドメインのプロキシホストを追加する
転送先: geoguessr-mcp-server:8000
Let's EncryptでSSLを有効にする

📖 詳細なVPSデプロイ手順については、DEPLOYMENT.mdを参照してください

方法3: 直接Dockerを使用して実行する

Docker Composeを使用しない場合は、以下のようにします。

# イメージを取得する
docker pull nyxiumyuuki/geoguessr-mcp:latest

# スキーマキャッシュ用のボリュームを作成する
docker volume create geoguessr-schemas

# コンテナを実行する（認証なし）
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MCP_AUTH_ENABLED=false \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  nyxiumyuuki/geoguessr-mcp:latest

# MCP認証を有効にして実行する
docker run -d \
  --name geoguessr-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e GEOGUESSR_NCFA_COOKIE=your_cookie \
  -e MCP_AUTH_ENABLED=true \
  -e MCP_API_KEYS=your-api-key-1,your-api-key-2 \
  -e MONITORING_ENABLED=true \
  -e MONITORING_INTERVAL_HOURS=24 \
  -e LOG_LEVEL=INFO \
  -v geoguessr-schemas:/app/data/schemas \
  nyxiumyuuki/geoguessr-mcp:latest

環境変数

変数	デフォルト	説明
`GEOGUESSR_NCFA_COOKIE`	-	GeoGuessr API認証クッキー
`MCP_AUTH_ENABLED`	false	MCPサーバー認証を有効にする
`MCP_API_KEYS`	-	MCPアクセス用のカンマ区切りのAPIキー
`MCP_PORT`	8000	サーバーポート
`MCP_TRANSPORT`	streamable-http	MCPトランスポートプロトコル
`MONITORING_ENABLED`	true	API監視を有効にする
`MONITORING_INTERVAL_HOURS`	24	監視チェック間隔（24時間ごとに実行）
`SCHEMA_CACHE_DIR`	/app/data/schemas	スキーマ永続化用のディレクトリ
`LOG_LEVEL`	INFO	ログの詳細度

🧪 開発

ローカル開発

# 仮想環境を作成する
python -m venv venv
source venv/bin/activate

# 依存関係をインストールする
pip install -r requirements-dev.txt

# テストを実行する
pytest -v

# サーバーをローカルで実行する
python -m geoguessr_mcp.main

プロジェクト構造

geoguessr-mcp/
├── src/geoguessr_mcp/
│   ├── api/              # APIクライアントとエンドポイント
│   ├── auth/             # 認証
│   ├── models/           # データモデル
│   ├── monitoring/       # スキーマ検出と監視
│   ├── services/         # ビジネスロジック
│   ├── tools/            # MCPツール定義
│   ├── config.py         # 設定
│   └── main.py           # エントリポイント
├── tests/
│   ├── unit/             # 単体テスト
│   └── integration/      # 統合テスト
├── nginx/                # 本番用nginx設定
├── docker-compose.yml    # 開発用デプロイ
├── docker-compose.prod.yml # 本番用デプロイ
└── Dockerfile