nulabg-mcp

MCP сървър за счетоводната платформа nula.bg. Дава на Claude и на други AI асистенти (Claude Desktop, Claude Code, Cursor, VS Code…) достъп до вашите фактури, покупки, OCR, клиенти, склад и банки чрез nula.bg API ключ.

Неофициален клиент. Проектът не е свързан с nula.bg. Работи върху публичното им REST API.

🇬🇧 In English: an MCP server for nula.bg, a Bulgarian cloud accounting platform — invoices, bills with OCR, customers, inventory, bank feeds and derived reports, over an API key. Read-only by default. Install the .mcpb bundle in Claude Desktop, or run npx -y nulabg-mcp with NULA_API_KEY set. The rest of this README is in Bulgarian, because the platform, its documents and its users are; the tool descriptions the model sees are in English. Issues and pull requests in either language are welcome.

Какво може

21 tools при разрешени промени, 13 в режим само за четене (по подразбиране), 25 с включени nra и noi. При няколко фирми се появява и nula_list_companies.

Освен това има:

• Prompts: issue-invoice, process-receipts, month-end-review, collect-overdue.
• Resources: основанията за 0% ДДС, основанията за протоколи, всички стойности на enum-ите и PDF на фактура.

Примерни заявки:

• „Издай фактура на ЕИК 123456789 за 10 часа консултации по 60 € без ДДС, платима по банка до 15 дни.“
• „Качи всички PDF-и от ~/Documents/Фактури/Септември като покупки и ми покажи какво е разпознато.“
• „Кои клиенти ми дължат пари от над 30 дни?“
• „Сравни входящите плащания по банковата сметка за септември с неплатените фактури.“

Инсталация

Нужен е API ключ от nula.bg, генериран от вашия акаунт в nula.bg. Ключът дава достъп до данните на фирмата, затова го пазете като парола.

🔒 По подразбиране сървърът е само за четене. Claude може да търси и чете, но не може да създава, редактира, изпраща или трие нищо в nula.bg. Така тестването и оценката са безопасни. За да разрешите промени, задайте NULA_READ_ONLY=false (в Claude Desktop: махнете отметката „Само четене“ в настройките на разширението).

Claude Desktop (препоръчително)

1. Свалете nulabg-mcp-<версия>.mcpb от Releases.
2. Отворете файла с двоен клик (или Settings → Extensions → Install Extension).
3. Въведете API ключа. Той се пази в keychain-а на системата. „Само четене“ е включено по подразбиране.

Node.js не е нужен, защото Claude Desktop го съдържа.

Claude Code

claude mcp add nulabg --scope user --env NULA_API_KEY=<вашият-ключ> -- npx -y nulabg-mcp

С право на промени (след като сте тествали):

claude mcp add nulabg --scope user --env NULA_API_KEY=<вашият-ключ> --env NULA_READ_ONLY=false -- npx -y nulabg-mcp

Cursor / Windsurf / Claude Desktop (ръчно)

~/.cursor/mcp.json или claude_desktop_config.json:

{
  "mcpServers": {
    "nulabg": {
      "command": "npx",
      "args": ["-y", "nulabg-mcp"],
      "env": { "NULA_API_KEY": "<вашият-ключ>" }
    }
  }
}

VS Code

.vscode/mcp.json. Ключът се иска при стартиране и не се записва във файла:

{
  "inputs": [{ "type": "promptString", "id": "nula-key", "description": "nula.bg API key", "password": true }],
  "servers": {
    "nulabg": {
      "command": "npx",
      "args": ["-y", "nulabg-mcp"],
      "env": { "NULA_API_KEY": "${input:nula-key}" }
    }
  }
}

Проверка на ключа от терминала:

NULA_API_KEY=<вашият-ключ> npx -y nulabg-mcp --check

Настройки

Няколко фирми (за счетоводители)

NULA_PROFILES='{"alfa":"ключ-1","beta":"ключ-2"}' NULA_DEFAULT_PROFILE=alfa npx -y nulabg-mcp

Всеки tool получава параметър company, а nula_list_companies показва наличните фирми без ключовете.

Безопасност

• Преглед преди създаване. nula_create_invoice и nula_create_bill имат preview_only. Асистентът е инструктиран първо да покаже номер, редове и суми и да изчака потвърждение.
• Потвърждение в клиента. Създаването, редакцията, изпращането по имейл и изтриването искат изрично „да“ чрез MCP elicitation, когато клиентът го поддържа. Tools, които изпращат или трият, са маркирани като destructive, така че клиентите искат одобрение.
• Изтриване. nula.bg трие само последната фактура. Tool-ът изисква номера ѝ (expected_number), отказва, ако последната е друга, и отказва предварително, ако фактурата е осчетоводена (виж „Ограничения“).
• Без повторни опити при запис. Заявки, които създават, променят, изпращат или трият, никога не се повтарят автоматично. При timeout отговорът казва „статусът е неизвестен, проверете преди нов опит“.
• Файлове. Четат се само PDF, JPG и PNG (по съдържание, не по разширение), само от NULA_FILE_ROOTS, без скрити папки, до 10 MB. URL-и се приемат само https, без локални и вътрешни адреси.
• Ключът. Не се логва и не се връща в отговори. Логовете отиват в stderr.
• Само четене по подразбиране. Докато не зададете изрично NULA_READ_ONLY=false, tools, които създават, променят, изпращат или трият, изобщо не се регистрират, така че Claude не може да ги извика. При грешно изписана стойност сървърът остава само за четене.
• Без подаване към НАП и НОИ. Подаването на декларации изисква КЕП и не е достъпно през този сървър.

Ограничения (v0.1)