Account Pool

account-pool-mcp

一个 MCP 服务，会一次向 Agent 会话分配一个测试账号，确保两个会话不会登录同一个账号。

问题

同时运行多个 Agent 会话时——例如几个 Claude 会话分别操控自己的 Playwright 浏览器——它们都需要登录。如果不加干预，它们会拿到同一个测试账号，互相干扰。两个会话共用一个账号会破坏彼此的状态，导致测试结果毫无意义。随机挑选账号也无济于事：有 10 个账号和 5 个会话时，发生冲突的可能性已经超过一半。

解决办法是租用账号。会话签出一个账号，使用后再归还。账号处于签出状态时，不会分配给其他人。

工作原理

服务会在一个小型 SQLite 数据库中维护账号池，并一次分配一个账号。分配操作在 BEGIN IMMEDIATE 事务中进行，因此即使多个会话在完全相同的时刻请求账号，也不会拿到同一个账号。每个租约都有 TTL，因此即使会话崩溃而未归还账号，账号也会自动回收——无需清理。

这一切都在后台进行。Agent 只需在需要账号时提出请求；经纪程序会决定分配哪个账号，并确保没有其他人持有该账号。没有共享的父进程——互不相关的会话完全通过数据库文件进行协调。

工具

• 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 秒的演示流程——两个会话分别租用不同账户，第三个会话会被正确拒绝，释放账户后，账户池会恢复可用。

项目已发布到 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" }，而非明文，这样真正的密钥就能保留在环境变量中，不会写入账户文件。

让 Agent 自动调用它

该服务会在 MCP 握手期间发送 Agent 指令——Claude Code、Cursor 和 Windsurf 等客户端会将其注入上下文，让 Agent 知道应在登录前调用 lease_account，无需每次都提醒。工具说明也会进一步强调这一点（租约是独占的；你必须释放）。

为确保 Agent 能可靠地获取这些指令，也请在项目自身的规则文件中添加一行（CLAUDE.md、.cursor/rules/、.windsurfrules），让 Agent 指令与服务端指令保持一致：

## 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 返回——日志记录器会对其进行遮蔽，且所有日志都会输出到 stderr，以免破坏 MCP 流。请勿将 accounts.json 和 *.db 提交到 git（仅提交 .example 文件）。stdio 服务信任在本地运行它的用户，因此请勿将其指向生产凭据。

限制

目前仅支持单主机：会话通过一个 SQLite 文件进行协调，因此必须共享文件系统。存储层封装在单个模块中，以后可以替换为 Postgres 或 Redis 后端，以支持多主机协调，而无需更改工具。