MobileValidate

@mobilevalidate/mcp

适用于 MobileValidate 的 Model Context Protocol 服务。它 可让 AI Agent（Claude Desktop、Claude Code、Cursor、VS Code 以及其他 MCP 客户端）查询电话号码信息——在 WhatsApp、Telegram、Viber、Signal 等平台上的注册情况、运营商和线路类型、基于举报的垃圾信息信誉——以及电子邮件地址信息（邮箱是否存在；是否拥有 Gmail、Outlook、Apple 等平台的账户；结果仅为是／否／未知，绝不提供姓名或 个人资料）。一次调用即可查询多项服务（checks）；list_services 可显示此密钥可使用的服务。

它是公共 MobileValidate API 的轻量客户端，基于 mobilevalidate SDK 构建。它不持有自己的凭据：你的密钥只会转发到 api.mobilevalidate.com。

有两种使用方式：

	托管（远程）	本地（stdio）
运行位置	https://mcp.mobilevalidate.com/mcp（Streamable HTTP）	在你的计算机上通过 npx -y @mobilevalidate/mcp 运行
密钥	标头 Authorization: Bearer <key>	环境变量 MOBILEVALIDATE_API_KEY
要求	无需安装任何内容	Node.js ≥ 20（npx 会下载软件包）

两种方式运行相同的工具，并采用相同的消费保护措施。可使用测试密钥试用：文档中列出的测试值会返回固定结果，且不会产生任何费用。

密钥：Agent 密钥（mv_agent_…，有使用范围限制，设有每日消费上限）或测试密钥（mv_test_…，免费，永不计费）。 MCP 服务会主动拒绝实时密钥（mv_live_…）。可在 https://mobilevalidate.com/get-test-key 获取个人测试密钥；Agent 密钥需搭配已获批准的账户使用。

文档：https://mobilevalidate.com/docs/mcp

快速开始（托管，使用测试密钥）

export MOBILEVALIDATE_API_KEY=mv_test_...     # your personal test key
claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \
  --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"

然后提问：“查询 +447700900001、+447700900002 和 +447700900003 在 WhatsApp 上的注册情况。” 你会得到已注册、未注册和未知三种结果。测试密钥不会访问真实网络，也永远不会产生费用：以下特殊值会返回固定结果，其他任何号码都会得到虚构但稳定的结果。

只是想看看？也可以使用公共沙盒密钥 mv_test_publicSandboxn9ZgneuhR1B9CRfKG3fulym，但它仅会返回以下特殊值的结果（其他任何值都会因 sandbox_magic_only 被拒绝），共享速率限制较低，也无法运行大型任务。如需进行更多操作，请使用自己的测试密钥。

测试号码	结果
+447700900001	已注册
+447700900002	未注册
+447700900003	未知（registered: null）
+447700900004	暂无结果，约 5 s 后显示已注册
+447700900005	unsupported_country
+447700900006	已注册，企业账户

测试电子邮件地址：[email protected]、not-registered@…、unknown@…（同一域名）。完整列表： https://mobilevalidate.com/docs/test-values。

客户端配置

Claude Code

# hosted
claude mcp add --transport http mobilevalidate https://mcp.mobilevalidate.com/mcp \
  --header "Authorization: Bearer $MOBILEVALIDATE_API_KEY"
# local stdio
claude mcp add mobilevalidate --env MOBILEVALIDATE_API_KEY=mv_agent_... -- npx -y @mobilevalidate/mcp

对应托管配置的 .mcp.json：

{
  "mcpServers": {
    "mobilevalidate": {
      "type": "http",
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${MOBILEVALIDATE_API_KEY}" }
    }
  }
}

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）

托管（实时）：

{
  "mcpServers": {
    "mobilevalidate": {
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MOBILEVALIDATE_API_KEY}" }
    }
  }
}

本地 stdio：{ "mcpServers": { "mobilevalidate": { "command": "npx", "args": ["-y", "@mobilevalidate/mcp"], "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." } } } }

VS Code（.vscode/mcp.json）

{
  "servers": {
    "mobilevalidate": {
      "type": "http",
      "url": "https://mcp.mobilevalidate.com/mcp",
      "headers": { "Authorization": "Bearer ${input:mobilevalidate-key}" }
    }
  },
  "inputs": [
    { "id": "mobilevalidate-key", "type": "promptString", "description": "MobileValidate agent or test key", "password": true }
  ]
}

Claude Desktop（claude_desktop_config.json）

Claude Desktop 通过社区维护的 mcp-remote 等 stdio 桥接工具，使用密钥连接远程服务（托管服务，实时）：

{
  "mcpServers": {
    "mobilevalidate": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mobilevalidate.com/mcp", "--header", "Authorization:Bearer ${MOBILEVALIDATE_API_KEY}"],
      "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." }
    }
  }
}

本地 stdio：

{
  "mcpServers": {
    "mobilevalidate": {
      "command": "npx",
      "args": ["-y", "@mobilevalidate/mcp"],
      "env": { "MOBILEVALIDATE_API_KEY": "mv_agent_..." }
    }
  }
}

其他 MCP 客户端

• Streamable HTTP： URL https://mcp.mobilevalidate.com/mcp，标头 Authorization: Bearer mv_agent_…。服务是无状态的：仅支持 POST，返回 JSON，不含会话 ID。
• stdio： 命令 npx，参数 ["-y", "@mobilevalidate/mcp"]，环境变量 MOBILEVALIDATE_API_KEY=mv_agent_…。 如需固定版本，请使用 @mobilevalidate/[email protected]。执行 npm install -g @mobilevalidate/mcp 后，命令为 mobilevalidate-mcp。

协议版本

两种传输方式均支持 MCP 2026-07-28 和基于握手的修订版 2025-11-25、2025-06-18、2025-03-26、 2024-11-05 和 2024-10-07（从 1.1.0 开始；1.0.x 最高支持 2025-11-25）。无需配置：客户端的首条 消息会选择修订版。

• **2026-07-28：**不使用 initialize；每个请求都携带 _meta（io.modelcontextprotocol/protocolVersion、客户端 信息和能力），通过 HTTP 传输时还会携带 MCP-Protocol-Version、Mcp-Method 和 Mcp-Name 请求头（会与正文 校验；不匹配时返回 400、-32020）。server/discover 会返回支持的版本、能力、服务身份和使用说明。 tools/list 和 server/discover 会携带 ttlMs: 3600000, cacheScope: "public" （每个密钥获取的列表都相同），工具按固定顺序返回。不支持的版本会收到 400，并返回列出支持版本的 UnsupportedProtocolVersion（-32022）。工具调用返回 JSON（不使用 SSE）。
• **2025 时代的客户端：**仍按原样使用 initialize；托管服务保持无状态（仅接受 POST，返回 JSON，不含会话 ID；GET → 405）。通过 stdio 建立的连接会保持协商好的修订版。
• 服务不会发送服务端到客户端的请求（sampling、elicitation、roots），也不使用协议日志记录，因此不会涉及 2026-07-28 中已弃用的内容。批量任务使用显式的 job_id 句柄，这是规范在会话机制取消后推荐的模式。
• 服务卡片的 supportedProtocolVersions 会按从新到旧的顺序列出相同版本。

工具

工具	功能	消耗额度	注释
normalize_numbers	本地免费进行 E.164 格式化。标记有歧义的输入（缺少国家/地区信息）和重复项	否	只读、幂等、封闭世界
estimate_cost	免费预检（号码和/或 emails）：统计有效、无效、重复和缓存数量，以及批量任务的最高费用	否	只读、幂等
lookup_numbers	使用一种或多种实时服务（checks）检查最多 100 个号码（可选包含 emails，总计 100 个）；最多等待 wait_seconds 秒，默认值为 20	是	非只读、幂等、开放世界
lookup_emails	实时检查最多 100 个电子邮件地址（默认检查 email；例如 apple.email）	是	非只读、幂等、开放世界
check_spam_reputation	查询最多 100 个号码的垃圾信息信誉（仅运行 number.spam）：每个号码返回 risk_level、risk_score、原因、主要类别、首次/最近发现时间、来源，以及各级别的数量	是	非只读、幂等、开放世界
create_lookup_job	使用任意有效服务批量检查（最多 50,000 个号码和/或 emails），包括仅支持批量检查的服务（例如 gmail）。返回 job_id	是	非只读、非幂等（参数相同的重试会被去重）
get_lookup_job	返回任务状态，以及经过筛选（registered、service）并分页的一页结果（每个号码或电子邮件一项）	否	只读、幂等
list_services	此密钥可使用的服务：输入类型（电话/电子邮件）、实时或仅支持批量、属性、国家/地区、价格	否	只读、幂等
get_account	余额、预留额度、今日用量、限额	否	只读、幂等

每个工具都会声明 title、注释、inputSchema 和 outputSchema。每个工具都会返回 structuredContent 以及一行文本摘要。checks 接受服务代码或别名（例如 whatsapp、telegram、viber、 carrier、spam）；其描述会列出此版本已知的实时和仅支持批量的代码（来自 SDK 生成的 目录），而 list_services 会提供实时列表。结果项会保留 v1 的顶层字段（若请求了 WhatsApp，则为 WhatsApp；否则为第一个服务），并在请求了多个服务（或请求了非 WhatsApp 服务）时，按服务添加 checks 映射。工具描述会说明反枚举限制（连续 ≥ 20 个号码会被拒绝，以及每日上限）。 电子邮件。 电话服务使用 numbers，电子邮件服务使用 emails；每种服务至少发送一次检查。结果项包含 kind（phone/email）；电子邮件项包含 email（已规范化，无效时为 null）、email_status（valid、invalid_email、duplicate、suppressed）和 number_status: null。描述中说明了电子邮件规则：同一域名下仅数字不同的地址达到 ≥ 20 个时，会被拒绝为枚举；答案仅限是/否/未知——不提供姓名、照片或个人资料。测试密钥使用 [email protected]、not-registered@…、unknown@…（同一域名）。

垃圾信息信誉。 check_spam_reputation（或在其他工具中使用 checks: ["spam"]）会根据垃圾信息和骚扰电话举报给出结果：监管机构采取的行动、政府投诉数据、社区举报和近期重新分配的号码。除受制裁国家和地区（古巴、伊朗、朝鲜、叙利亚、俄罗斯、白俄罗斯、委内瑞拉及受制裁地区）外，所有国家均支持 → unsupported_country，免费。no_reports 表示没有已知举报，并不表示该号码安全；这仍是明确结论，且会计费。限制：每次调用 ≤ 100 个号码；与 lookup_numbers 使用相同的支出确认和反枚举规则。测试密钥：+447700900001 为 high，…002 为 no_reports，…003 为 unknown，…004 先为 pending，随后为 medium，…005 为 unsupported_country。属性值可以是整数（risk_score、sources）。

网络检查。 checks: ["hlr"] 会返回实时网络状态（status 为 reachable / unreachable / invalid、ported、roaming、mcc_mnc、country）；checks: ["mnp"] 会返回号码携转状态（porting 为 ported / not_ported、mcc_mnc、country）。未知结果免费。

支出安全

在 lookup_numbers、lookup_emails、check_spam_reputation 或 create_lookup_job 产生任何费用之前，服务端会调用免费估算接口。实时工具按密钥的实时价格（来自 list_services）计算最高费用，create_lookup_job 则按批量价格计算。符合以下任一条件时，调用会被拒绝，并返回 confirmation_required 错误结果：

• 最高费用超过 MCP_CONFIRM_ABOVE_USD（默认值为 1.00），或
• 一个任务包含超过 100 个电话号码和电子邮件地址。

权限范围（Agent 密钥）：实时工具需要 lookup:write 和 jobs:write（估算接口为 POST /v1/jobs/estimate）；estimate_cost 和 create_lookup_job 需要 jobs:write；get_lookup_job 需要 jobs:read；get_account 需要 account:read。list_services 无需权限。

错误文本会说明金额，并提示 Agent 询问用户。随后，Agent 会将显示的金额设为 confirm_max_cost，再次调用该工具。确认金额（或估算金额）始终会作为 max_cost 发送至 API，因此 API 会拒绝任何费用更高的请求。

限制： 此确认由 Agent 代为处理。服务端无法证明用户是否批准了该金额。硬性限制为密钥自身的支出上限和 max_cost 防护。后续计划提供人工确认 URL。

其他规则：

• 仅接受 mv_agent_…（受权限范围限制并设有支出上限）和 mv_test_… 密钥。拒绝 mv_live_… 密钥，并提供明确说明。
• 没有 webhook_url 参数，且绝不会将请求元数据回显到工具输出中。
• 日志写入 stderr，且仅包含数量和 ID。任何看起来像电话号码或电子邮件地址的内容都会被屏蔽。

环境变量

环境变量	默认值	用途
MOBILEVALIDATE_API_KEY	无（必填）	stdio：mv_agent_/mv_test_ 密钥
MOBILEVALIDATE_BASE_URL	https://api.mobilevalidate.com	两者均使用。
MCP_CONFIRM_ABOVE_USD	1.00	两者均使用
MCP_HOST / MCP_PORT	127.0.0.1 / 3300	HTTP
MCP_ALLOWED_HOSTS	无	HTTP：允许的额外 Host 值（以逗号分隔），例如在反向代理后运行时
MCP_LOG	开启	设为 off 可关闭 stderr 日志
MV_MCP_FORWARD_SECRET	无	仅用于 HTTP 托管部署：与 API 共享的密钥，使沙盒密钥调用按每个终端客户端（而非每台服务）进行速率限制
MCP_CLIENT_IP_HEADER	cf-connecting-ip	HTTP：包含终端客户端 IP 的标头，仅信任来自环回对等端（隧道/代理）的标头

自托管 HTTP 传输

MCP_HOST=127.0.0.1 MCP_PORT=3300 npx -y -p @mobilevalidate/mcp mobilevalidate-mcp-http   # once published

仅支持 POST /mcp（无状态、JSON 响应；2026-07-28 和 2025 年时代的客户端共用同一端点）和 GET /healthz。每个请求的 Authorization: Bearer 密钥仅针对该请求转发 到 API，从不存储。Host 必须为 127.0.0.1:<port> 或 localhost:<port>，以及 MCP_ALLOWED_HOSTS 中的任意 值（DNS 重绑定保护）——将服务置于反向代理后时请设置此项，并在其前端终止 TLS。请求正文大小限制为 2 MB。

安全说明

• 使用设有你能接受的支出上限的 Agent 密钥（mv_agent_…）；密钥的上限和 max_cost 防护是 硬性限制。测试密钥免费。
• 将密钥放在客户端的 env / 标头配置中，而不是提示词里。服务绝不记录密钥；其 stderr 日志仅包含计数和 ID，且看起来像电话号码或电子邮件地址的内容都会被屏蔽。
• 超过 MCP_CONFIRM_ABOVE_USD 的支出需要 Agent 先询问用户（见 支出安全）；此流程由 Agent 处理，因此请将密钥的支出上限设为真正的限制。
• 仅检查用户有正当关系的号码和地址。系统会拒绝枚举模式，并设有每日上限。

维护者

源代码是 src/ 中的 TypeScript（在 monorepo 中使用 tsx 直接运行：HTTP 使用 pnpm --filter @mobilevalidate/mcp start 在 127.0.0.1:3300 上启动，stdio 使用 start:stdio）。发布包仅包含编译后的 dist/、 README.md、LICENSE 和 server.json；publishConfig 会将 main / exports / bin 从 src/ 切换到 dist/，而 pnpm 会将 workspace:* SDK 依赖重写为确切的 SDK 版本——因此始终使用 pnpm 打包（ops/publish-packages.sh），切勿在此目录中直接运行 npm pack / npm publish。构建会针对 SDK 的 dist/ 类型进行编译，因此请先构建 SDK。

MCP SDK：此服务使用官方 v2 TypeScript SDK（@modelcontextprotocol/server，它通过双时代服务实现 2026-07-28：HTTP 使用 createMcpHandler + isLegacyRequest，stdio 使用 serveStdio）。v1 包 @modelcontextprotocol/sdk 和 @modelcontextprotocol/client 仅作为开发依赖：测试会将它们用作真实的 2025-11-25 客户端和真实的 2026-07-28 客户端（test/protocol.test.ts）。

pnpm --filter @mobilevalidate/mcp run typecheck
pnpm --filter @mobilevalidate/mcp test
pnpm --filter mobilevalidate run build && pnpm --filter @mobilevalidate/mcp run build   # → dist/
ops/publish-packages.sh                     # build, test, pack, leak-scan, npm publish --dry-run (SDK, then MCP)
NPM_TOKEN=… ops/publish-packages.sh --yes   # real publish

发布检查清单：更新 package.json 中的 version、src/tools.ts 中的 SERVER_VERSION，以及 server.json 中的两个 version 字段（测试会确保它们一致）。必须先发布 SDK，因为此包会锁定其确切 版本。

**MCP Registry。**以 com.mobilevalidate/mcp（已验证域名的命名空间）列出。server.json 遵循注册表 架构 2025-12-11；package.json 中的 mcpName 必须与其 name 相同（注册表会在 npm 上检查）。

许可证

MIT © 2026 BroadNet Technologies Inc. 参见 LICENSE。