iiko-mcp

MCP-сервер для ручной отладки запросов к iikoTransport API (api-ru.iiko.services). Подключается к любому MCP-клиенту (Cursor, Claude Desktop, Claude Code) и даёт инструменты, чтобы дёргать эндпоинты iiko и смотреть сырые ответы — со своими кредами.

EN: An MCP server for debugging iikoTransport API requests. Bring your own credentials, plug it into any MCP client, and call iiko endpoints interactively.

Авторизация — v2 (POST /api/v2/access_token с apiKey/appId/clientSecret, JWT на 1 час, кэшируется в памяти). Старый /api/1/access_token отключается iiko.

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

git clone https://github.com/steamn/iiko-mcp.git
cd iiko-mcp
npm install
npm run build

Дальше — задать креды (см. ниже) и подключить в MCP-клиенте.

Креды

Получаются один раз:

1. Зарегистрируй приложение на портале разработчика iiko — https://public-api.iikoweb.ru/portal. Получишь appId и одноразовый clientSecret.
2. В iikoWeb → Интеграции → API-ключи сгенерируй API-ключ (apiKey).

Переменная окружения	Значение
IIKO_API_LOGIN	apiKey из iikoWeb
IIKO_APP_ID	appId с портала разработчика
IIKO_CLIENT_SECRET	clientSecret с портала (показывается один раз)
IIKO_BASE_URL	необязательно, по умолчанию https://api-ru.iiko.services
IIKO_TIMEOUT_MS	необязательно, по умолчанию 30000

Есть два способа передать креды:

• через MCP-клиент — в блоке env конфига (примеры ниже);
• через .env-файл — скопируй .env.example в .env, заполни и запускай node --env-file=.env dist/index.js.

.env в .gitignore — секреты в репозиторий не попадут.

Инструменты

Инструмент	Назначение
iiko_request	Универсальный: любой метод + путь + тело, авто-авторизация → статус, correlationId, тело
iiko_access_token	Получить/обновить токен (для отладки авторизации)
iiko_organizations	POST /api/1/organizations
iiko_nomenclature	POST /api/1/nomenclature
iiko_stop_lists	POST /api/1/stop_lists
iiko_deliveries_by_id	POST /api/1/deliveries/by_id

iiko_request — главный: им можно вызвать любой эндпоинт из документации iiko, даже если готового шортката нет.

Подключение

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "iiko": {
      "command": "node",
      "args": ["/absolute/path/to/iiko-mcp/dist/index.js"],
      "env": {
        "IIKO_API_LOGIN": "your-api-key",
        "IIKO_APP_ID": "your-app-id",
        "IIKO_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json

Тот же блок mcpServers. После правки конфига перезапусти клиент — инструменты iiko_* появятся в списке.

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

• Никогда не коммить реальные clientSecret/apiKey. Держи их в .env (он в .gitignore) или в конфиге MCP-клиента вне репозитория.
• Если секрет утёк — перевыпусти его на портале разработчика, старый отзовётся.

Разработка

npm run dev   # tsc --watch

PR и issue приветствуются.

Лицензия

MIT © steamn