Account Pool

account-pool-mcp

エージェントセッションにテストアカウントを一度に1つずつ割り当てるMCPサーバーです。2つのセッションが同じアカウントにログインすることはありません。

問題

複数のエージェントセッションを同時に実行する場合、たとえばそれぞれが独自のPlaywrightブラウザーを操作するClaudeセッションがいくつかある場合、どのセッションもログインする必要があります。何もしなければ、同じテストアカウントを取得して互いに干渉してしまいます。1つのアカウントを2つのセッションで使うと、互いの状態が壊れ、テスト結果は意味をなさなくなります。ランダムにアカウントを選んでも、あまり役に立ちません。アカウントが10個、セッションが5つある場合、すでに衝突する可能性のほうが高くなります。

解決策は、アカウントを貸し出すことです。セッションがアカウントを借りて使用し、使い終わったら返却します。貸し出し中のアカウントがほかのセッションに渡されることはありません。

仕組み

サーバーはアカウントのプールを小さなSQLiteデータベースに保持し、1つずつ貸し出します。割り当てはBEGIN IMMEDIATEトランザクション内で行われるため、複数のセッションがまったく同時に要求しても、同じアカウントが複数に渡されることはありません。各貸し出しにはTTLが設定されているため、セッションがアカウントを返却せずにクラッシュしても、自動的に再利用可能な状態に戻ります。後片付けは必要ありません。

これらはすべてバックグラウンドで処理されます。エージェントは必要なときにアカウントを要求するだけです。ブローカーが割り当てるアカウントを決定し、ほかのセッションに同じアカウントが渡らないことを保証します。共有の親プロセスはなく、無関係なセッション同士もデータベースファイルを通じて連携します。

ツール

• lease_account(pool, holder?) — アカウントを借ります。アカウント、認証情報、およびlease_tokenを返します。使い終わるまで保持してください。
• release_account(lease_token) — アカウントを返却します。何度実行しても安全です。
• renew_lease(lease_token) — 作業が長引く場合に、貸し出し期間を延長します（ハートビート）。
• pool_status(pool?) — 貸し出し中と空きの状況を確認します。認証情報の値は返しません。

同じデータベースを使う、小さなaccount-pool CLI（lease／release／renew／status）もあります。スクリプトや人間が利用できます。

セットアップ

まず試してみますか？ bash examples/demo.sh を実行すると、インストール不要の60秒間のデモを確認できます。2つのセッションが異なるアカウントをリースし、3つ目は正しく拒否され、リリースするとプールが回復します。

npm で公開されているため、クローンやビルドは不要です。MCP クライアント（例：.mcp.json）に登録してください。初回起動時に npx が取得してキャッシュします。

{
  "mcpServers": {
    "account-pool": {
      "command": "npx",
      "args": ["-y", "account-pool-mcp"],
      "env": {
        "APM_ACCOUNTS_FILE": "./accounts.json",
        "APM_DB_PATH": "./account-pool.db"
      }
    }
  }
}

次に、accounts.json でプールを定義します（アカウントごとに id と認証情報のオブジェクトを指定します）。

{ "pools": { "realtor": [
  { "id": "realtor_01", "credentials": { "username": "[email protected]", "password": { "env": "REALTOR_01_PW" } } }
] } }

CLI も使いますか？ npx account-pool status でその場で実行するか、PATH にインストールしてください。

npm install -g account-pool-mcp     # adds `account-pool` (CLI) and `account-pool-mcp` (server)

すべてのセッションの APM_DB_PATH を同じファイルに設定してください。この共有ファイルを通じてセッション間で連携します。

環境変数	デフォルト	説明
APM_ACCOUNTS_FILE	./accounts.json	起動時に読み込むプールとアカウントです。
APM_DB_PATH	./account-pool.db	SQLite ファイルです。すべてのセッションで同じパスを指定します。
APM_DEFAULT_TTL_SECONDS	1800	リースが再取得可能になるまでの時間です。
APM_LEASE_WAIT_MS	0	0 = プールが空の場合、すぐに失敗します。>0 = アカウントが空くまでこの時間待機します。

認証情報の値には、リテラルの代わりに { "env": "VAR_NAME" } を指定できます。これにより、実際のシークレットを環境変数に保持し、アカウントファイルには含めずに済みます。

エージェントが自動的にこのツールを使うようにする

このサーバーは MCP ハンドシェイクでエージェント向けの指示を送信します。Claude Code、Cursor、Windsurf などのクライアントはこれをコンテキストに追加するため、エージェントは毎回指示されなくても、ログイン前に lease_account を呼び出す必要があると認識します。ツールの説明でも、リースは排他的であり、必ず解放する必要があることを明示しています。

より確実に反映させるには、プロジェクト独自のルールファイル（CLAUDE.md、.cursor/rules/、.windsurfrules）にも一文を追加し、エージェント向けの指示とサーバー側の指示が一致するようにしてください。

## Test accounts
This repo has account-pool-mcp configured. Before logging into any test account in a QA or
Playwright run, call `lease_account` to check one out, and `release_account` when done.
Never hard-code, guess, or reuse an account — one account per session at a time.

セキュリティ

これらはテスト用アカウントであり、シークレット保管庫ではありません。認証情報の値がログに記録されたり、pool_status から返されたりすることはありません。値はマスキング機能を備えたロガーによって秘匿され、すべてのログは MCP ストリームを破損させないよう stderr に出力されます。accounts.json と *.db は Git に含めないでください（コミットされるのは .example ファイルのみです）。stdio サーバーはローカルで実行するユーザーを信頼するため、本番環境の認証情報を指定しないでください。

制限事項

現時点では単一ホストのみです。連携には1つの SQLite ファイルを使用するため、すべてのセッションでファイルシステムを共有する必要があります。ストレージ層は1つのモジュール内に分離されているため、後から Postgres または Redis のバックエンドに差し替えれば、ツールを変更せずに複数ホスト間で連携できます。