NUM

NUM MCP 服务

让你的 Agent 找到真实地点。 面向旅行场景的远程 MCP 服务：搜索包含超过 250 万个地点的目录——餐厅、酒吧、酒店、水疗中心、旅行团和商店，数据最丰富的地区是泰国和英国——并提交商家或促销信息，供人工审核。

# Claude Code
claude mcp add --transport http num https://itsnum.com/mcp

**Claude 和 ChatGPT：**将 https://itsnum.com/mcp 添加为自定义连接器，登录 NUM 并批准即可。无需密钥。

由 5arz Inc. 运营 · 端点：https://itsnum.com/mcp · 已列入官方 MCP Registry， 名称为 com.itsnum/num。

此仓库包含文档、连接配置和客户端示例。 服务本身托管在云端——无需安装或运行任何内容。

快速开始

发现工具是开放的。无需任何凭据即可查看服务提供的工具：

curl -sS -X POST https://itsnum.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

调用工具需要先登录。有两种方式，共享同一配额。

**1. 登录（OAuth 2.1）——适用于 Claude、ChatGPT、Cursor、VS Code 及任何支持 MCP 授权的客户端。**只需向客户端提供 URL。首次调用工具时会打开 NUM 登录窗口；批准 num.read（搜索）和 num.write（提交）即可。支持 PKCE 和动态客户端注册；元数据位于 https://itsnum.com/.well-known/oauth-protected-resource。访问权限有效期为一小时，并会自动续期。你可以随时从客户端断开连接。

2. 免费 API 密钥——适用于脚本、服务端和不支持 OAuth 的客户端：

curl -sS -X POST https://itsnum.com/api/agent/signup \
  -H 'content-type: application/json' \
  -d '{
        "agent_name": "Acme Listings Bot",
        "operator_name": "Acme Ltd",
        "operator_email": "[email protected]",
        "purpose": "Suggest restaurants and bars to travellers in Thailand."
      }'

密钥只会返回一次，无法找回。请立即保存。 使用 POST /api/agent/me/rotate 轮换密钥；使用 GET /api/agent/me 查看用量。

以上所有内容的可运行版本都在 examples/ 中。

连接

**传输方式：**Streamable HTTP。**身份验证：**OAuth 2.1，或 Authorization: Bearer numa_live_…。 使用 OAuth 时，请从以下任一配置中删除 headers 块。

{
  "mcpServers": {
    "num": {
      "type": "http",
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer numa_live_YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "num": {
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer numa_live_YOUR_KEY" }
    }
  }
}

{
  "servers": {
    "num": {
      "type": "http",
      "url": "https://itsnum.com/mcp",
      "headers": { "Authorization": "Bearer ${input:num_key}" }
    }
  },
  "inputs": [
    { "id": "num_key", "type": "promptString", "description": "NUM API key", "password": true }
  ]
}

连接后可以询问的问题

• 帮我找出普吉岛芭东的三家泰餐厅，并提供可以拨打的电话号码。
• 爱丁堡列出了哪些水疗中心？显示第一家的完整记录。
• NUM 目录中有哪些曼谷屋顶酒吧？哪些已由店主认领？
• 我在普吉岛卡塔经营一家咖啡馆。请以店主身份将它提交给 NUM。详情如下：……
• 显示我提交给 NUM 的所有内容，以及审核人员的决定。

工具

这五个工具都带有 title 和 MCP 工具注解。三个读取工具设有 readOnlyHint； 两个提交工具设有 destructiveHint，因为重新发送相同的 external_ref 或 promo_ref 会覆盖待审核的提交内容，因此行为规范的客户端会先征求用户同意。

**配额 — 每日读取次数：**免费版 100 次 · 套餐版 2,000 次 · 专业版 20,000 次 · 完整版 200,000 次。 所有套餐的写入次数均不限，包括免费版。比起收取费用，我们更希望获得你的数据。

构建之前，有两件事值得了解

**提交内容不会自动发布。**通过 num_submit_business 或 num_submit_promo 发送的所有内容都会被保存，但在 5arz 的工作人员批准之前，旅客无法看到。这是有意为之，也没有办法插队。 不要因为工具返回成功，就告诉用户其商家信息已上线 — 请轮询 num_list_submissions，查看审核人员的决定。

这里的“已验证”有特定含义，并非评价分数。在 NUM 中， 已验证描述的是个人或已认领的商家信息，绝不描述地点：

• 已验证旅客是指 5arz 确认其为独一无二的真实人士的旅客。
• 已验证商家信息是指其所有者已证明拥有该信息中已公布联系方式的控制权。
• 未认领的商家信息已录入地图，但未经验证。

如果你向最终用户展示 NUM 数据，请勿将“已验证”呈现为质量、评分或背书标志。它只表示此人是真实的或此所有者是真实的 — 与食物是否美味无关。

如实说明关系

num_submit_business 会询问你与商家的关系，所选值很重要：

为了显得更可信而猜选 owner，是导致 Agent 密钥被吊销的最快方式。 切勿编造联系方式 — 无法接通的电话号码比留空更糟。

速率限制与使用规范

• 读取次数按套餐每日计量；写入次数不计量。
• 每个地址每天最多注册 5 个密钥。每个 Agent 一个密钥就够了 — 请重复使用。
• 429 表示你触及了限制。请稍后重试；不要在短时间内循环重试。

发现入口

定价

API 和 MCP 服务均免费：每天可读取 100 次，提交次数不限。更高的读取配额与商家控制面板采用相同套餐，每月 $9.99 起。

旅客免费使用，也不收取旅客预订费。商家可免费发布信息，仅在 NUM 完成预订时付费：餐桌预订收取 10%，客房预订收取 15%，活动预订收取 20%，费用由商家承担，绝不会加到旅客账单上。未到场和被拒绝的预订均不收费。 详情请见 itsnum.com/pricing。

支持

• 问题、错误、合作：[email protected]
• 隐私政策 · 条款
• 安全：请参阅 SECURITY.md
• 欢迎通过此仓库提交有关文档和客户端示例的问题。

许可

本仓库中的文档和示例：MIT。 NUM 服务、其数据和目录本身均为 5arz Inc. 的专有内容， 且不受本仓库许可。