invoices-mcp

MCP-сервер сервиса выставления счетов и актов: счета, акты, контрагенты, договоры, оплаты, номенклатура, отчёты, публичные ссылки — для любого MCP-клиента (Claude Desktop, Claude Code, Cursor, VS Code, собственный агент).

Версия: 0.1.3 · Node.js: 20+ · Транспорт: stdio (по умолчанию) или Streamable HTTP. Пакет ставится прямо из этого репозитория, без сборки на вашей машине и без публикации в npm.

Что умеет

• 34 инструмента. Чтение: организации, контрагенты и их карта взаимоотношений, документы и оплаты по ним, договоры, номенклатура, отчёты (сводка, дебиторка, акт сверки, реестр), публичные ссылки. Запись: создание контрагента, позиции, черновика счёта или акта, выдача, аннулирование, удаление черновика, оплаты, договоры, ссылки. Любая изменяющая операция требует confirm: true — без него запрос в API вообще не уходит.

• 6 ресурсов-шаблонов (invoice://, invoice://…/pdf, act://, contractor://, organization://, contract://) — карточки для чтения моделью по ссылке.

• 4 промпта — готовые сценарии: счёт по описанию, сводка по контрагенту, разбор дебиторки, акт по счёту.

Права определяет только токен: readonly-токен не сможет ничего изменить, и MCP не даёт способа это обойти.

Related MCP server: Invoice MCP Server

Установка

Через npx из git (рекомендуется)

npx -y github:valderan/invoices-mcp#v0.1.3

Первый запуск занимает больше времени: npm скачивает пакет и четыре его зависимости (@modelcontextprotocol/*, zod). Дальше они берутся из кеша (~/.npm/_npx).

Указывайте тег (#v0.1.3), а не #main: npm кеширует по коммиту, и без тега легко остаться на старой копии.

Локально

git clone https://github.com/valderan/invoices-mcp.git
cd invoices-mcp
npm install --omit=dev
INVOICES_API_URL=https://crm.example.ru INVOICES_API_TOKEN=ivs_… node dist/index.js

Проверить версию и справку можно без настройки:

npx -y github:valderan/invoices-mcp#v0.1.3 --version   # invoices-mcp 0.1.3
npx -y github:valderan/invoices-mcp#v0.1.3 --help

Настройка

Только переменные окружения — файлов конфигурации нет.

Подключение в агентах

Везде одна схема: команда npx, аргументы с тегом, токен в env.

Claude Desktop

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

{
  "mcpServers": {
    "invoices": {
      "command": "npx",
      "args": ["-y", "github:valderan/invoices-mcp#v0.1.3"],
      "env": {
        "INVOICES_API_URL": "https://crm.example.ru",
        "INVOICES_API_TOKEN": "ivs_AbCdEf12_…"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (или .cursor/mcp.json в проекте) — тот же блок mcpServers.

Claude Code

claude mcp add invoices \
  --env INVOICES_API_URL=https://crm.example.ru \
  --env INVOICES_API_TOKEN=ivs_AbCdEf12_… \
  -- npx -y github:valderan/invoices-mcp#v0.1.3

VS Code

.vscode/mcp.json — ключ servers:

{
  "servers": {
    "invoices": {
      "command": "npx",
      "args": ["-y", "github:valderan/invoices-mcp#v0.1.3"],
      "env": {
        "INVOICES_API_URL": "https://crm.example.ru",
        "INVOICES_API_TOKEN": "ivs_AbCdEf12_…"
      }
    }
  }
}

HTTP-режим

Если клиент умеет Streamable HTTP, сервер можно держать запущенным отдельно:

INVOICES_MCP_TRANSPORT=http INVOICES_MCP_PORT=7331 \
INVOICES_API_URL=https://crm.example.ru INVOICES_API_TOKEN=ivs_… \
npx -y github:valderan/invoices-mcp#v0.1.3

Клиент подключается к http://127.0.0.1:7331/mcp. Сервер слушает только loopback и проверяет Host/Origin (защита от DNS rebinding): подключиться с другой машины нельзя, для этого нужен обратный прокси. Плюс режима — токен не лежит в конфиге каждого пользователя.

Токены и приватность

• Токен даёт ровно те права, что выданы при его создании: readonly — только чтение, full — чтение и запись. MCP не расширяет доступ и не обходит 403.

• Сервер отправляет данные в модель, включая локальные: суммы, названия контрагентов, ИНН, номера документов. Если это неприемлемо для ваших клиентов — используйте readonly-токен и ограничьте доступ на стороне API.

• Токен хранится в конфиге клиента. Утечка конфига = утечка токена: заводите отдельный токен на каждую машину и отзывайте его в админке, раздел «Токены».

• В логах сервера только публичная часть токена (kid), суммы и содержимое документов не пишутся.

Ошибки

Ответ инструмента ограничен 64 КБ: длинные списки сокращаются, в тексте появляется подсказка — уточните фильтры или передайте cursor из предыдущего ответа.

Версии

Версионирование — SemVer, каждая версия помечена тегом vX.Y.Z, история — в CHANGELOG.md. Устанавливайте с тегом: github:valderan/invoices-mcp#v0.1.3.

Совместимость: новые инструменты и необязательные поля — minor; исправления поведения — patch; удаление или переименование инструмента, обязательного аргумента или поля ответа — major.

Лицензия

Проприетарная: использовать разрешено, копировать, распространять, изменять и встраивать в свои продукты — нет. Полный текст — в LICENSE.