NUM MCP-сервер

Реальные места для вашего агента. Удалённый MCP-сервер для путешествий: поиск в каталоге из

более чем 2,5 миллиона мест — ресторанов, баров, отелей, спа-салонов, экскурсий и магазинов. Наиболее полный каталог представлен

в Таиланде и Великобритании. Также можно отправлять на проверку владельцами бизнеса сведения о компаниях и акциях.

# 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

под именем 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": "ops@acme.example",
        "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 из любой приведённой ниже конфигурации.

Claude Desktop / Claude Code

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

Cursor — .cursor/mcp.json

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

VS Code — .vscode/mcp.json

{
  "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, и решения проверяющего.

Инструменты

Инструмент	Назначение	Учитывается в квоте
`num_search_places`	Поиск по произвольному тексту, городу, стране или категории. Нужно указать хотя бы один параметр.	Да — чтение
`num_get_place`	Получение полной записи о месте по `place_id`.	Да — чтение
`num_submit_business`	Отправка сведений о компании. Перед публикацией их проверяет сотрудник.	Нет
`num_submit_promo`	Публикация акции, специального предложения, события или рекламы для отправленной вами компании.	Нет
`num_list_submissions`	Просмотр всех отправленных вами данных и решений проверяющего.	Нет

У всех пяти инструментов есть title и аннотации MCP. У трёх инструментов для чтения указано readOnlyHint, а у двух инструментов для отправки — destructiveHint: повторная отправка того же external_ref или promo_ref перезаписывает ожидающие проверки данные. Поэтому корректно работающий клиент сначала должен спросить пользователя.

Квоты на чтение в сутки: бесплатный тариф — 100 · bundle — 2 000 · pro — 20 000 · full — 200 000.

Количество операций записи не ограничено ни на одном тарифе, включая бесплатный. Нам важнее получить ваши данные, чем деньги.

Два важных момента перед началом работы

Отправленные данные не публикуются автоматически. Всё, что передаётся через

num_submit_business или num_submit_promo, сохраняется, но остаётся невидимым для путешественников, пока сотрудник 5arz не одобрит публикацию. Это сделано намеренно; обойти проверку нельзя.

Не сообщайте пользователю, что его запись опубликована, только потому, что инструмент вернул успешный результат. Проверяйте решение через num_list_submissions.

У слова «verified» здесь особое значение: это не оценка качества. В NUM статус verified относится к человеку или заявленной владельцем записи, но не к месту:

Проверенный гость — путешественник, личность которого 5arz подтвердил как уникального реального человека.
Проверенная запись — запись, владелец которой подтвердил контроль над контактными данными, уже указанными в ней.
Незаявленные записи нанесены на карту, но не проверены.

Если вы показываете данные NUM конечным пользователям, не используйте статус «verified» как показатель качества, рейтинг или знак одобрения. Он означает только «это реальный человек» или «этот владелец — реальный человек» — и ничего не говорит о качестве еды.

Честно указывайте связь с компанией

В num_submit_business нужно указать, как вы связаны с компанией. Выбранное значение имеет значение:

Значение	Описание
`owner`	Вы или ваш оператор владеете компанией
`authorized_agent`	Компания поручила вам действовать от её имени
`third_party`	Вы добавляете известное вам место, не будучи связанным с ним

Указание owner ради большей достоверности — самый быстрый способ лишиться ключа агента.

Не выдумывайте контактные данные: недоступный номер телефона хуже, чем пустое поле.

Ограничения запросов и рекомендации

Для операций чтения действуют суточные квоты, зависящие от тарифа; количество операций записи не ограничено.
За сутки можно зарегистрировать не более 5 ключей с одного адреса. Одного ключа на агента достаточно — используйте его повторно.
Ответ 429 означает, что вы достигли лимита. Сделайте паузу и не повторяйте запросы в быстром цикле.

Ресурсы для изучения

Ресурс	Адрес
Манифест MCP	`https://itsnum.com/.well-known/mcp.json`
Карточка MCP-сервера	`https://itsnum.com/.well-known/mcp/server-card.json`
Метаданные OAuth	`https://itsnum.com/.well-known/oauth-protected-resource`
OpenAPI (эквивалент REST)	`https://itsnum.com/openapi.json`
Краткое описание простым языком	`https://itsnum.com/llms.txt`
Полный текстовый корпус	`https://itsnum.com/llms-full.txt`
Данные о компаниях в машиночитаемом формате	`https://itsnum.com/for-ai/`
Документация платформы для агентов	`https://itsnum.com/agents/`

Цены

API и MCP-сервер бесплатны: 100 операций чтения в день, количество отправок не ограничено. Более высокие квоты на чтение доступны в рамках тех же тарифов, что и бизнес-панель, начиная с $9.99 в месяц.

Для путешественников сервис бесплатен, комиссия за бронирование не взимается. Компании размещают данные бесплатно и платят только за бронирования, которые NUM успешно завершает: 10% за столик, 15% за номер, 20% за мероприятие. Комиссия удерживается с компании и не добавляется к счёту путешественника. За неявку или отклонённое бронирование плата не взимается.

Подробности — на странице itsnum.com/pricing.

Поддержка

Вопросы, сообщения об ошибках и предложения о сотрудничестве: info@itsnum.com
Политика конфиденциальности · Условия использования
Информация по вопросам безопасности — в файле SECURITY.md
Будем рады сообщениям об ошибках документации и примеров для клиентов в разделе Issues этого репозитория.

Лицензия

Документация и примеры в этом репозитории распространяются по лицензии MIT.

Сервис NUM, его данные и сам каталог являются собственностью 5arz Inc.

На них не распространяется лицензия этого репозитория.