Gosar MCP サーバー

Claude がユーザーに代わって Gosar API を呼び出せるようにする MCP サーバーで、Gosar の OAuth 2.0 + PKCE フローで認証されます。

これはブリッジとして機能します:

• Claude（MCP クライアント）に対しては、完全な OAuth 認可サーバーのように動作します — 動的クライアント登録を処理し、独自の短期トークンを発行します。

• Gosar に対しては、Gosar の統合ガイドに記載されている実際の Authorization Code + PKCE 交換を実行する、単一の事前登録済み OAuth クライアント（公開、PKCE のみ）です。

前提条件

• Python 3.11+

• Gosar チームに登録された Gosar OAuth クライアント（統合ガイドの「What we need from you」を参照）— client_id と承認済みリダイレクト URI が必要です。

• 実際の Gosar API に対してテストする場合は ngrok（または類似のもの）— Gosar のリダイレクト URI は HTTPS で完全に一致する必要があり、Claude もリモート MCP サーバーに接続するために HTTPS URL を必要とします。

Related MCP server: Strava MCP Server

1. 依存関係のインストール

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. .env の設定

取得した値をプロジェクトルートの .env にコピーします:

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

署名キーを生成します（Gosar はシークレットのない公開クライアントであるため、自動的に導出できません — 必須です）:

python -c "import secrets; print(secrets.token_urlsafe(32))"

出力を JWT_SIGNING_KEY に貼り付けます。再起動後も同じ値を維持してください。そうしないと、接続中のすべてのユーザーがログアウトされます。

3. サーバーを HTTPS で公開する（実際の Gosar テスト用）

Claude と Gosar はどちらも HTTPS を必要とします。別のターミナルで:

ngrok http 8000

https://...ngrok-free.app URL を .env の MCP_PUBLIC_BASE_URL にコピーし、{MCP_PUBLIC_BASE_URL}/gosar/callback を登録済みリダイレクト URI として Gosar チームに送信します。

4. サーバーの実行

source .venv/bin/activate
python main.py

次のように表示されるはずです:

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

コード変更時の自動リロード

python main.py はリロードされません — mcp.run() はブロックし、独自の uvicorn プロセスを所有するため、ファイル監視リローダーに渡すことはできません。開発時は、代わりに gosar_mcp/asgi.py の ASGI アプリを uvicorn で直接実行してください:

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload は .py ファイルが変更されるたびにワーカープロセスを再起動します。

• --reload-include ".env" は .env を編集したときにも再起動します（uvicorn はデフォルトで Python ファイルのみを監視し、環境変数はプロセス起動時に一度だけ読み取られるため、このフラグがないと .env の編集には手動再起動が必要です）。

• ポートを ngrok トンネルが指すものと同期させてください。

5. OAuth 配線の健全性チェック

サーバーが実行されている状態で、ディスカバリメタデータが提供されていることを確認します:

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

scopes_supported に applications.read/applications.write が含まれ、PKCE メソッドとして S256 のみが含まれているはずです。

6. Claude に接続する

Claude のコネクタ設定で、次の場所を指すリモート MCP サーバーを追加します:

https://your-tunnel.ngrok-free.app/mcp

Claude はこのサーバーに対して OAuth クライアントとして自己登録し、ユーザーを同意画面にリダイレクトし、その後 Gosar の実際の Google サインイン + 同意画面を経由して、アクティブな接続でここに戻ってきます。Claude に whoami ツールを呼び出して、期待どおりの Gosar アカウントとして認証されていることを確認させてください。

注記

• トークンストレージ（クライアント登録 + 暗号化されたアップストリーム Gosar トークン）は、デフォルトで OS に適した暗号化ファイルストアをディスク上に使用します — ローカル開発には追加設定は不要です。本番環境で別のバックエンドを指定する場所については gosar_mcp/auth.py を参照してください。

• gosar_mcp/tools.py の /applications エンドポイントパスはプレースホルダーです — 統合ガイドでは OAuth レイヤーのみが指定されており、Applications REST API の形状は指定されていません。実際のパス/ペイロードを Gosar チームに確認し、そこで調整してください。