informer-mcp

Сервер Model Context Protocol для бухгалтерского API Informer (v2). Он даёт любому MCP-клиенту прямой доступ к вашим контрагентам, счетам продаж и покупок, котировкам, заказам, квитанциям, товарам и финансовым отчётам.

Каждый инструмент извлечён из собственного OpenAPI-документа Informer (api.informer.eu/docs/v2). Его копия поставляется вместе с сервером, так что сервер работает офлайн, но остаётся актуальным — см. Поддержание актуальности при изменениях API.

Неофициальный проект. Не связан с Informer и не одобрен компанией Informer.

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

Вставьте это в любого ИИ-ассистента, который умеет устанавливать MCP-серверы:

Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

Он клонирует репозиторий, соберёт проект, зарегистрирует сервер в вашем клиенте, а затем запустит informer-mcp setup — после чего в браузере на 127.0.0.1 откроется страница. Здесь вводятся ваши учётные данные API; в чате ничего не спрашивают, и никакой ключ никогда не попадает в переписку.

Что вы видите на этой странице

По одной карточке на администрацию, а если у вас их больше одной — ещё и кнопка Добавить администрацию:

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

Оба учётных данных привязаны к одной администрации, поэтому бухгалтер добавляет по одной карточке на каждого клиента. Подробнее — в разделе Несколько клиентских администраций.

Что происходит при нажатии «Проверить и сохранить»

1. Каждая пара «ключ/секретный код» проверяется через API, и страница показывает название компании, которой она на самом деле принадлежит: если ключ вставлен не в ту строку, это видно до сохранения.

2. Если пара отклонена, ничего не записывается, а проблемная строка называется. Отметьте Сохранить без проверки, чтобы сохранить её в любом случае, например при работе офлайн.

3. В случае успеха данные записываются в ~/.informer-mcp.json с правами 0600. Если страница открыта через open_setup, работающий сервер подхватывает изменение сразу — новая администрация становится доступной в самом следующем сообщении. Если страница открыта из терминала, перезапустите клиент.

Спросите «к каким администрациям у вас есть доступ?», чтобы проверить это — запрос вызывает list_administrations и перечисляет каждый псевдоним с его компанией.

Related MCP server: billingo-mcp

Что вы получаете

• 68 инструментов — все 49 документированных конечных точек — чтение и запись.

• Настройка в браузере. Попросите ассистента открыть страницу настройки или запустите informer-mcp setup. Он проверяет каждый ключ через API, записывает файл конфигурации, и изменение вступает в силу без перезапуска.

• Следует за API. Когда Informer публикует новую конечную точку, сервер подхватывает её и добавляет инструмент, пока клиент остаётся подключён, — без переустановки и перезапуска.

• Несколько клиентских администраций в одном сервере. Бухгалтер может работать с книгами всех клиентов из одного подключения: аргумент administration становится обязательным, как только настроено более одной администрации.

• Один запрос по всему портфелю. Инструменты только для чтения принимают список псевдонимов или "all" и опрашивают их параллельно, возвращая результаты, сгруппированные по клиенту.

• Полные схемы запросов. Инструменты создания/обновления рекламируют полную JSON Schema для своей полезной нагрузки, поэтому модель знает нужные поля и правила до отправки.

• Выбор режима. Флаг --read-only скрывает все изменяющие инструменты, а отдельные клиенты могут оставаться доступными только для чтения, пока остальные — для записи. Списки разрешённых и запрещённых инструментов сужают поверхность ещё сильнее.

• Загрузка PDF и вложений — декодируются из base64 и записываются сразу на диск.

• Устойчивый HTTP. Таймауты, повторные запросы с поддержкой Retry-After, а голландCache сообщения валидации Informer возвращаются дословно (HTTP 422: invoice_date: ongeldig).

Требования

• Node.js 20 или новее

• Аккаунт InformerOnline с доступом к API

Настройка учётных данных

Просто спросите в разговоре:

«Я хочу изменить свои администрации Informer» «Добавить нового клиента в Informer» «Мой API-ключ Informer изменился»

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

Та же страница, но из терминала:

npm run setup          # or: informer-mcp setup

В любом случае вы получаете http://127.0.0.1:<port> в браузере — с формой для каждой администрации: псевдоним, название компании, API-ключ, секретный код и флажок разрешения на запись. Сохранение проверяет каждую пару через API, поэтому опечатка в ключ видна сразу, а вы видите, какой компании принадлежит каждый ключ, и затем записывает ~/.informer-mcp.json с правами 0600.

Если запустить сервер вообще без учётных данных, он автоматически откроет ту же страницу, ведь именно в этот момент она вам нужна. Установите INFORMER_AUTO_SETUP=false, чтобы отключить это, или INFORMER_OPEN_BROWSER=false на машине без браузера, чтобы только вывести URL. Как бы ни была открыта, страница всегда одна: повторный запрос возвращает тот же URL.

Что страница делает намеренно:

• она привязывается только к 127.0.0.1, и при каждом запуске генерируется случайный токен, который должен быть и в URL, и в запросе сохранения, чтобы никакой другой сайт в вашем браузере не мог отправить туда POST-запрос;

• она никогда не отправляет сохранённые ключи обратно на страницу — существующие администрации показываются с пустыми учётными данными и сохраняются, если вы не введёте новое значение;

• она refuses сохранять учётные данные, которые API отклоняет, если вы не отметите опцию Сохранить без проверки.

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

Откуда берутся ключи

API аутентифицируется через два заголовка, оба обязательны:

Оба привязаны к одной администрации: API-ключ принадлежит той администрации, в которой он создан (GET /administration возвращает «администрацию, связанную с этим API-ключом»), а секретный код идентифицирует конкретную компанию. Не существует конечной точки, которая перечисляла бы администрации или переключала между ними.

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

Несколько клиентских администраций

Бухгалтеру с несколькими клиентами нужна пара «ключ/секретный код» для каждой клиентской администрации — ее может создать пользователь-бухгалтер, имеющий доступ к администрации. Добавьте их на странице настройки или запишите ~/.informer-mcp.json (или любой файл, указанный INFORMER_CONFIG_FILE) самостоятельно:

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

Если настроено более одной администрации, каждый инструмент требует аргумент administration, который в схемах объявляется как перечисление ваших псевдонимов:

list_sales_invoices({ "administration": "acme", "filter": "open" })

Значения по умолчанию намеренно нет. Записать счёт в бухгалтерскую книгу не того клиента — ошибка, которая не должна случиться тихо, поэтому вызов без этого аргумента отклоняется проверкой схемы ещё до любого HTTP-запроса; отклоняется и никогда не настроенный псевдоним.

list_administrations показывает настроенные псевдонимы; передайте verify: true, чтобы получить название компании из API для каждого — это подтвердит и что ключи работают, и что каждый псевдоним указывает на ту компанию, на которую вы и ожидали.

Запрос к нескольким клиентам сразу

Инструменты только для чтения также принимают список псевдонимов или "all":

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

Администрации запрашиваются параллельно (число управляется INFORMER_FANOUT_CONCURRENCY, по умолчанию четыре одновременно), а ответ группируется по псевдонимам:

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

Три свойства, о которых стоит знать:

• Сбой одного клиента не роняет весь запрос. Его строка получит error, а остальные по-прежнему вернут данные.

• Бюджет ответа делится поровну. Каждая администрация получает INFORMER_MAX_RESPONSE_CHARS / n символов, поэтому один большой клиент не вытесняется весь остальных; все, что сверх его доли, возвращается в виде { "truncated": true, "partial": ... }.

• Распределение только для чтения. Инструменты, которые пишут, а также скачивание PDF/вложений принимают только один псевдоним. В их схемах даже нет массива или "all", и показатель оснований повторно отклоняет их. Не стоит разрешить случайно создать один и тот же счёт в двенадцати администрациях.

При одной администрации API-ответ по-прежнему возвращается как есть, без обёртки, — то что было раньше.

В случае одной администрарии (самый распространённый случай) ничего не меняется: задайте INFORMER_API_KEY and INFORMER_SECURITY_CODE as it was before, and the argument remains optional.

Установка

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

Страница настройки запускается на 127.0.0.1, проверяет каждый ключ через API и записывает ~/.informer-mcp.json. См. Настройка учётных данных.

Claude Desktop, в качестве расширения

Самый простой путь — собрать пакет и открыть его.

npm run bundle          # writes informer-mcp.mcpb

В Claude Desktop перейдите в Настройки → Расширения → Дополнительные настройки → Установить расширение… и выберите файл .mcpb. Он содержит все свои зависимости, так что предварительно устанавливать ничего, кроме Node.js 20, не требуется.

В диалогскаустановке предлагаются API-ключ, секретный код и переключатель только для чтения. Все три можно оставить пустыми: тогда сервер при первом запуске откроет свою страницу настройки — это также единственный способ настроить более одной администрации.

Обратите внимание: Settings → Connectors → Add custom connector в Claude Desktop — это другая возможность: она принимает URL удалённого MCP-сервера. Наш сервер работает локально через stdio, поэтому ставится как расширение, а не как подключение.

Claude Desktop, вручную

Отредактируйте файл конфигурации напрямую:

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

После этого перезапустите Claude Desktop. В Windows обратная косая черта в JSON должны быть удвоены; прямой слеш тоже работает и его проще читать.

Любой другой MCP-клиент

Сервер говорит по протоколу MCP через stdio, поэтому любой клиент настраивается одинаково — это команда и аргументы. Блок выше работает как есть в Claude Code (claude mcp add), Cursor, Zed и в других MCP-совместимых программах.

Учётные данные берутся из ~/.informer-mcp.json, поэтому их не нужно повторять в конфигурации клиента. Если их нужно передать отдельно для каждого клиента, добавьте блок env с переменными INFORMER_API_KEY и INFORMER_SECURITY_CODE, либо укажите INFORMER_CONFIG_FILE в другом месте.

Добавьте "--read-only" в args, чтобы зарегистрировать сервер, который не может ничего изменить — см. Read-only or read-write. Регистрация одного и того же сервера дважды под двумя именами, один read-only и один read-write, работает хорошо.

stdout несёт протокол, поэтому всё логирование идёт в stderr — однострочный баннер при запуске сообщает, сколько инструментов было зарегистрировано и какие администрации он нашёл.

Read-only or read-write

По умолчанию доступен каждый инструмент. Чтобы полностью убрать записывающие инструменты, запустите сервер с флагом:

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

INFORMER_READ_ONLY=true делает то же самое, и флаг имеет приоритет над переменной — так вы можете зарегистрировать один и тот же сервер дважды в одном клиенте, один раз read-only для повседневных вопросов и один раз read-write для сессий, где вы действительно что-то бронируете.

В режиме read-only записывающие инструменты вообще не регистрируются: они никогда не появляются в списке инструментов, так что модели не за что зацепиться.

Per client

Отдельные администрации можно закрепить в конфигурационном файле — это удобная форма, когда вам разрешено смотреть только на книги некоторых клиентов:

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

"read_only": true работает как сокращение. Побеждает самое ограничительное значение:

Таким образом, клиент, помеченный как read-only, никогда не может быть случайно записан, а сессия, запущенная с --read-only, остаётся такой, что бы ни говорил конфигурационный файл.

Когда одни администрации доступны для записи, а другие нет, записывающие инструменты остаются зарегистрированными, но их перечисление administration предлагает только доступные для записи. Запрос на создание счёта в read-only клиенте отклоняется до любого HTTP-запроса:

Administration(s) bakkerij are configured as read-only, so this tool cannot change them.
Writable: acme, garage.

list_administrations сообщает фактический режим каждого клиента, а стартовый баннер резюмирует его: read-write: acme, garage.

Configuration

Фильтры принимают либо тег OpenAPI, либо имя инструмента и сопоставляются без учёта регистра и пунктуации:

# read-only access to invoicing data
INFORMER_TOOLS="Sales Invoices,Relations" node dist/index.js --read-only

# everything except deleting attachments
INFORMER_EXCLUDE_TOOLS=delete_sales_invoice_attachment node dist/index.js

Using it

После подключения спрашивайте на простом языке:

• «Какие счета-фактуры по продажам за 2026 год ещё не оплачены?» → list_sales_invoices с filter

• «Создай черновик счёта для ACME на 10 часов консультаций по €125.» → get_sales_invoice_options для валидных id главной книги/НДС/шаблона, затем create_sales_invoice

• «Скачай счёт 12345 в формате PDF на мой рабочий стол.» → get_sales_invoice_pdf с save_path

• «Покажи балансовый отчёт за период 6 2026 года.» → get_balance_report

Conventions worth knowing

• Выбирайте администрацию явно. При нескольких настроенных клиентах каждый инструмент принимает administration: "<alias>". list_administrations сопоставляет псевдонимы с компаниями, а read-only инструменты также принимают список или "all".

• Даты всегда в формате YYYY-MM-DD.

• Инструменты списков разбиты на страницы через page (по умолчанию 1) и records (по умолчанию 20) и возвращают объект pagination с total и pages.

• Полезная нагрузка запроса передаётся одним аргументом body. Параметры пути и запроса остаются на верхнем уровне, поэтому update_relation принимает { "id": 42, "body": { ... } }.

• Сначала вызывайте инструмент *_options при создании документов. get_sales_invoice_options, get_quotation_options и подобные возвращают валидные id главной книги, НДС, шаблона, валюты и условий оплаты для вашей администрации.

• Отчёты требуют явных диапазонов. get_balance_report требует year_from, year_to и period; get_column_balance_report также требует диапазон главной книги.

PDFs and attachments

Informer возвращает файлы в base64 внутри JSON. Инструменты, которые это делают (get_*_pdf, download_sales_invoice_attachment), принимают необязательный save_path:

• с save_path — файл декодируется и записывается по этому пути, а инструмент возвращает { saved_to, filename, bytes, mime_type };

• без него — файл возвращается как встроенный ресурс MCP с правильным MIME-типом, что для больших документов может быть дорого по контексту.

Загрузка работает наоборот: upload_sales_invoice_attachment принимает { filename, file }, где file — содержимое в base64 (макс. 10 МБ; PDF, PNG, JPEG, GIF, DOC(X), XLS(X)).

Tool reference

npm run tools печатает этот список из текущей спецификации; npm run tools -- --md перегенерирует таблицы ниже.

Помимо инструментов конечных точек есть три серверных:

Administration

Relations

Contacts

Sales Invoices

Purchase Invoices

Повторяющиеся счета

Заказы на продажу

Котировки

Книга продаж

Условия оплаты

Шаблоны

НДС

Главные книги

Затраты

Валюты

Журналы

Типы подписок

Вложения

Товары

Квитанции

Меморандум

Отчеты

Именование инструментов

Имена образуются от HTTP-метода и пути, а не от описания, поэтому они остаются стабильными при обновлениях спецификации:

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

Отслеживание изменений API

Инструменты генерируются из документа OpenAPI от Informer, поэтому когда Informer добавляет конечную точку, единственное, чего не хватает, — это свежая копия этого документа. Сервер может получить её сам.

Три уровня, в порядке приоритета:

1. Скачанная копия, кэшируемая в ~/.informer-mcp.spec.json.

2. Встроенная копия в openapi/api-docs.json, которая поставляется с сервером и всегда работает офлайн.

3. Ни одна из них не принимается вслепую — загрузка должна разобраться как документ OpenAPI 3 хотя бы с одной рабочей операцией, иначе она отклоняется, а текущие инструменты остаются. Портальная страница или страница обслуживания не могут стереть ваш набор инструментов.

По расписанию

Раз в день, вскоре после запуска, сервер в фоновом режиме проверяет наличие более нового документа. Запуск никогда не блокируется, а неудачная проверка записывается в журнал и игнорируется. INFORMER_SPEC_MAX_AGE_HOURS=0 отключает эту проверку.

По запросу

Инструмент refresh_api_spec делает то же самое, когда вы его вызываете, — это полезно, если ожидаемая конечная точка отсутствует или аргумент отклоняется как неизвестный:

«Обнови описание API Informer и расскажи, что изменилось».

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

Передайте dry_run, чтобы увидеть этот отчет без применения изменений.

Различие намеренно конкретное: оно называет инструменты, которые появились и исчезли, а для изменившихся говорит, что именно изменилось — новый аргумент, удалённый аргумент, поле, которое теперь стало обязательным. Это та часть, которую не видно при простом сравнении путей, и обычно именно она иначе проявилась бы как непонятная ошибка 422.

Применение документа обновляет работающий сервер: регистрируются новые инструменты, удаляются отозванные, изменённые рекламируются заново, и отправляется уведомление tools/list_changed, чтобы ваш клиент перезагрузил список в середине сеанса.

Копия в репозитории

npm run update-spec обновляет встроенный документ и сообщает, какие пути пришли и ушли. Именно эту команду нужно запускать, если вы хотите зафиксировать изменение для всех, кто устанавливает сервер; refresh_api_spec влияет только на вашу машину.

Ресурсы

Сервер также предоставляет сам документ OpenAPI как ресурс MCP по адресу informer://openapi.json — это удобно, когда нужно, чтобы модель проверила определение поля, не гадая.

Разработка

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

Структура проекта

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb

Добавление конечных точек обычно вообще не требует изменения кода — работающий сервер подхватывает их сам, а npm run update-spec фиксирует то же изменение во встроенной копии. Только действительно новые формы URL требуют правила в таблице RESOURCES в src/openapi.ts; без него они всё равно становятся инструментами, просто с более скучным именем.

Как преобразуются схемы

OpenAPI 3.0 — это не совсем JSON Schema. На пути к определению инструмента MCP:

• ссылки #/components/schemas/X становятся #/$defs/X, при этом встраивается только транзитивное замыкание, которое реально нужно каждой операции, — поэтому определения инструментов остаются компактными;

• nullable: true становится объединением ["type", "null"];

• параметры пути и запроса становятся свойствами верхнего уровня, тела запросов помещаются под body, а additionalProperties: false не даёт опечаткам дойти до API.

Аргументы проверяются по этой схеме до любого HTTP-вызова.

Примечания по безопасности

• Этот сервер может создавать, обновлять и удалять реальные бухгалтерские записи. Начните с --read-only, если вам нужна только отчётность, закрепите отдельных клиентов с помощью "mode": "read-only" и позвольте вашему MCP-клиенту запрашивать подтверждение для инструментов записи.

• Учётные данные для нескольких клиентов в одном процессе означают, что один ошибочно направленный вызов может затронуть чужие книги. Обязательный аргумент administration, перечень известных псевдонимов, ограничение только на чтение при рассылке и префикс псевдонима в каждом сообщении об ошибке ([acme] HTTP 422: ...) существуют именно для этого. Держите файл конфигурации вне системы контроля версий и доступным только для чтения вами.

• Инструменты аннотированы с помощью readOnlyHint, destructiveHint и idempotentHint, поэтому клиенты, использующие эти подсказки, могут ограничивать доступ к рискованным.

• Ничего не записывается в stdout, и учётные данные никогда не отображаются в выводе инструментов и не отправляются обратно на страницу настройки. open_setup возвращает URL, а не ключ — у ассистента нет способа прочитать ваши учётные данные и нет причин просить их в чате.

• Описание API загружается без учётных данных, и документ, который не разбирается как пригодный файл OpenAPI 3, отклоняется, а не принимается.

Лицензия

MIT — см. LICENSE.