openrusrouter-mcp

Клиентский MCP-сервер (stdio) для openrusrouter.ru: каталог моделей с ценами вашего аккаунта, баланс, расход и список API-ключей — прямо из Claude, Cursor, OpenCode или любого другого MCP-агента.

Пакет: @openrusrouter/mcp, команда: openrusrouter-mcp.

Инструменты

Все шесть инструментов — только чтение (помечены readOnlyHint), сервер делает только GET-запросы к API площадки.

Инструмент	Что делает
list_models	Список моделей с фильтрами (модальность, вендор, подстрока, контекст, vision, бесплатные) и сортировкой. Цены — ₽ за 1M токенов с персональной наценкой вашего аккаунта. По умолчанию — только модели, доступные текущему ключу.
pick_model	Подбор моделей под требования (модальность, vision, контекст, потолок цены, ожидаемый объём токенов). Локальный фильтр по ценам каталога, не рекомендация ИИ; только среди моделей, доступных текущему ключу.
estimate_cost	Оценка стоимости запроса по числу токенов: cost_rub — по рублёвым ценам аккаунта без скидки за кэш, cost_usd — по USD-ценам каталога с ценой кэш-чтения, если модель её объявляет.
get_balance	Текущий баланс аккаунта в рублях и реферальный баланс (decimal-строки).
get_usage	Расход за последние N дней (1–180) с группировкой по дню, модели, ключу или ключу и модели: запросы, токены, сумма в ₽.
list_api_keys	Список API-ключей: префикс, лимит расхода и его окно, израсходовано, разрешённые модели. Полный ключ не выводится никогда; is_current_key отмечает ключ, которым работает MCP.

Чего тут нет и почему

Создание, отзыв и правка API-ключей, платежи, промокоды и тикеты через MCP не делаются — и не появятся.

MCP-сервер ходит в API тем же Bearer-ключом, что и обычный API-вызов: сервер openrusrouter.ru их не различает. А решение вызвать инструмент принимает ИИ-агент, а не человек, нажавший кнопку, — и агентом можно управлять через содержимое, которое он читает (prompt injection). Поэтому платёжные и ключевые мутации по такому каналу сознательно не допускаются: на площадке они доступны только из браузерной сессии личного кабинета.

Быстрый старт

Нужен Node.js ≥ 20.

1. Заведите отдельный ключ под MCP

В личном кабинете создайте отдельный API-ключ специально для MCP: с небольшим лимитом расхода (spend_limit_rub) и, по возможности, ограниченным списком моделей (allowed_models). Не используйте мастер-ключ без ограничений — почему, см. Безопасность.

2. Подключите сервер к клиенту

Claude Desktop — claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "openrusrouter": {
      "command": "npx",
      "args": ["-y", "@openrusrouter/mcp"],
      "env": {
        "OPENRUSROUTER_API_KEY": "<ваш ключ>"
      }
    }
  }
}

Claude Code (CLI):

claude mcp add openrusrouter -e OPENRUSROUTER_API_KEY=<ваш ключ> -- npx -y @openrusrouter/mcp

Проектный .mcp.json (Claude Code) или .cursor/mcp.json (Cursor) — та же форма mcpServers:

{
  "mcpServers": {
    "openrusrouter": {
      "command": "npx",
      "args": ["-y", "@openrusrouter/mcp"],
      "env": {
        "OPENRUSROUTER_API_KEY": "<ваш ключ>"
      }
    }
  }
}

Если файл лежит в репозитории, не коммитьте в него ключ: подставляйте его из окружения ("${OPENRUSROUTER_API_KEY}" в Claude Code, "${env:OPENRUSROUTER_API_KEY}" в Cursor).

OpenCode — opencode.json, блок mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openrusrouter": {
      "type": "local",
      "command": ["npx", "-y", "@openrusrouter/mcp"],
      "enabled": true,
      "environment": {
        "OPENRUSROUTER_API_KEY": "<ваш ключ>"
      }
    }
  }
}

OpenCode по умолчанию ждёт список инструментов 5 секунд; первый запуск через npx скачивает пакет и может не уложиться — тогда добавьте "timeout": 30000.

Переменные окружения

Переменная	Обязательна	Описание
OPENRUSROUTER_API_KEY	да	API-ключ из личного кабинета. Без него сервер не стартует.
OPENRUSROUTER_BASE_URL	нет	Адрес API, по умолчанию https://openrusrouter.ru. Допускается только https (http — только для localhost/127.0.0.1/::1), без логина/пароля, query-параметров и фрагмента.

Внимание: ключ уходит в заголовке Authorization на OPENRUSROUTER_BASE_URL. Переопределив адрес, вы отправляете свой ключ на указанный хост — на свой риск. При нестандартном адресе сервер на старте пишет в stderr, на какой хост будет отправляться ключ.

Безопасность

• Нет телеметрии. Сервер обращается только к OPENRUSROUTER_BASE_URL.
• Ключ не пишется никуда: ни в stdout, ни в stderr, ни в сообщения об ошибках, ни в результаты инструментов (list_api_keys отдаёт только префиксы).
• В stdout идёт только протокол MCP. Диагностика — в stderr.
• Кэш каталога — в памяти процесса на 10 минут, на диск ничего не пишется.
• Отдельный ограниченный ключ. MCP делает только GET-запросы и платных вызовов моделей не совершает, но ключ в конфиге агента лежит открытым текстом — в файле, который читают другие программы, попадает в бэкапы и легко оказывается в репозитории. Тем же ключом можно ходить в прокси к моделям за ваш счёт. Отдельный ключ с небольшим spend_limit_rub и узким allowed_models ограничивает ущерб при утечке, и его можно отозвать в кабинете, не трогая остальные интеграции.

Ограничения

• У image-, transcription- и speech-моделей цена за токен не публикуется — они тарифицируются по факту. estimate_cost для них возвращает ошибку, а не ноль.
• Каталог площадки может содержать модели, недоступные текущему ключу (из-за allowed_models). По умолчанию list_models их скрывает; include_disallowed=true покажет их явно. pick_model подбирает только среди доступных.
• Оценка стоимости — это оценка: фактическое списание идёт по usage ответа провайдера.

Разработка

npm ci
npm run typecheck
npm test
npm run build
npm run lint
npm run gen:types   # регенерация типов из живой OpenAPI-спеки

Лицензия

MIT — см. LICENSE.