NULA.BG

nulabg-mcp

用于会计平台 nula.bg 的 MCP 服务。通过 nula.bg API 密钥，让 Claude 和其他 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code…）访问您的发票、采购、OCR、客户、库存和银行数据。

非官方客户端。 本项目与 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.

功能

模块（工具集）	工具	功能
core	nula_lookup_company	按公司统一识别码或增值税号查询公司（商业登记处 / VIES）
invoices	nula_search_invoices, nula_create_invoice, nula_update_invoice, nula_update_invoice_metadata, nula_get_invoice_pdf, nula_email_invoice, nula_delete_last_invoice	搜索、开具（带预览）、编辑、标记为已付款/已发送、管理类别和附件、获取 PDF、通过电子邮件发送、删除最后一张发票
bills	nula_search_bills, nula_create_bill, nula_update_bill_categories	采购，包括《增值税法》第 117 条规定的协议
ocr	nula_ocr_upload, nula_ocr_status	从磁盘上传最多 10 份文档、等待识别、查看配额
customers	nula_search_customers	客户和交易对手
inventory	nula_search_items, nula_list_item_categories	商品、价格、科目、库存
banking	nula_list_bank_accounts, nula_list_bank_transactions	银行账户和交易
insights	nula_receivables_report, nula_period_summary, nula_match_bank_transactions	含账龄分析的应收款、月度汇总、银行交易 ↔ 发票的对账建议
nra（默认禁用）	nula_nra_declarations, nula_nra_refresh_result	国家税务局申报状态（不提交申报）
noi（默认禁用）	nula_noi_documents, nula_noi_get_document	国家社会保障研究所的文档（附录 9/10/11）

启用更改后有 21 个工具，只读模式下（默认）有 13 个，启用 nra 和 noi 后有 25 个。 如果有多家公司，还会显示 nula_list_companies。

此外还包括：

• 提示词： issue-invoice、process-receipts、month-end-review、collect-overdue。
• 资源： 0% 增值税的依据、协议依据、所有枚举值以及发票 PDF。

示例请求：

• “给公司统一识别码为 123456789 的客户开具发票，内容为 10 小时咨询服务，每小时 60 €，不含增值税，通过银行转账付款，期限为 15 天。”
• “将 ~/Documents/Фактури/Септември 中的所有 PDF 上传为采购单，并告诉我识别出了哪些内容。”
• “哪些客户欠款超过 30 天？”
• “将 9 月银行账户的入账与未付款发票进行比较。”

安装

需要 nula.bg API 密钥，可在您的 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_API_KEY	—	API ключ (задължителен, освен ако не ползвате NULA_PROFILES)
NULA_READ_ONLY	true	Само четене. Промени в nula.bg се разрешават само с изрично false (0, no, off). Всяка друга стойност, вкл. грешно изписана, оставя режима само за четене
NULA_TOOLSETS	core,invoices,bills,ocr,customers,inventory,banking,insights	Кои модули да са активни; all включва и nra, noi
NULA_CONFIRM_WRITES	elicit	Потвърждение в клиента преди създаване, изпращане и изтриване (ако клиентът поддържа elicitation); never го изключва
NULA_DEFAULT_CURRENCY	EUR	Валута за нови документи
NULA_DEFAULT_LANGUAGE	bg	Език на PDF и имейл (bg / en)
NULA_DEFAULT_INVOICE_CATEGORY	—	Категория за нови фактури (nula.bg изисква поне една)
NULA_DOWNLOAD_DIR	~/Downloads/nula	Къде се записват PDF и XML
NULA_FILE_ROOTS	~	Папки, от които може да се качват файлове (разделени с :, на Windows с ;)
NULA_PROFILES	—	Няколко фирми: {"firma-a":"ключ1","firma-b":"ключ2"} или път до JSON файл
NULA_DEFAULT_PROFILE	default или първият	Фирма по подразбиране при NULA_PROFILES
NULA_BILL_CALLBACK_URL	https://nula.bg/	Адрес, който nula.bg уведомява след създаване на покупка (вижте „Ограничения“)
NULA_BASE_URL	https://nula.bg
NULA_TIMEOUT_MS / NULA_MAX_CONCURRENCY / NULA_LOG_LEVEL	30000 / 4 / info

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

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）

• 已于 26.09.2026 使用真实账户验证。 所有 13 个读取工具以及写入操作（开具、编辑、已付款/已发送、PDF、电子邮件）均可处理真实数据。响应格式记录在 docs/research/nula-api-analysis.md §8–§9 中。唯一无法通过的是删除，详见下文。由于密钥无权访问，未测试 OCR、НАП 和 НОИ。
• OCR、НАП 和 НОИ 需要拥有公司访问权限的密钥。 使用在个人资料中创建的密钥时，这些 endpoint 会返回 403“此令牌未限定到你有权访问的团队”。其他模块均可正常工作。
• 商品： SKU 搜索通过遍历目录实现，因为 /open-cart/products/{sku} 和 getItemDetails 即使对现有商品也会返回 404，而 search 筛选器不会按 SKU 搜索。
• 按 id 获取采购： /ocr/bill/{id} 仅适用于经过 OCR 处理的文档；对于其他文档，服务器会从列表中查找采购记录。
• “已发送”发票： nula.bg 不会返回此类状态，因此 nula_update_invoice_metadata 要求同时提供两个标志（is_paid 和 is_sent），或提供发票编号。
• 通过 API 删除发票通常无法实现。 DELETE /api/v1/deleteInvoice 在不带参数的情况下调用，会删除最后开具的发票，但对于已入账的文档会返回 HTTP 403（错误消息为空）。在启用了会计模块的公司中，所有发票都会显示 has_accounting: true，因此无法通过 API 删除，必须在 Web 应用中手动删除文档或开具贷项通知单。此工具会预先检查这一点，而不是发送注定失败的请求。
• 采购的回调 URL。 createBill 需要 callback_url。默认情况下会传入 nula.bg 自身的地址，因此数据不会发送给第三方。如果你有自己的 webhook，请设置 NULA_BILL_CALLBACK_URL。
• 缺少的 API 操作。 nula.bg API 不支持创建或编辑交易对方（客户会在开具首张发票时自动创建）、按 id 获取发票、查询增值税和付款记录。

开发

npm install
npm run build        # TypeScript → dist/
npm test             # unit + протоколни тестове (Vitest, фалшив nula.bg API)
npm run lint         # Biome
npm run inspect      # MCP Inspector срещу dist/cli.js
npm run pack:mcpb    # Claude Desktop bundle → nulabg-mcp-<версия>.mcpb
node dist/cli.js --list-tools

技术栈：

• TypeScript；
• @modelcontextprotocol/server 2.x（MCP spec 2026-07-28，也兼容 2025 年的客户端）；
• zod 4；
• Node.js ≥ 20。

架构与决策：docs/SPEC.md。调研：docs/research/。

发布： 步骤和发布前检查见 docs/RELEASING.md。简而言之：在 package.json 中提升版本，更新 CHANGELOG.md，并创建 vX.Y.Z tag；GitHub Actions 会发布到 npm 并附带 provenance，将 .mcpb 附加到 GitHub Release，并更新 MCP Registry。

贡献

欢迎提交 Issues 和 pull requests，可使用保加利亚语或英语。最有帮助的是报告与真实 API 不符之处（字段名称和类型，不含真实数据），因为官方文档几乎只描述请求。

• 如何参与项目：CONTRIBUTING.md
• 社区准则：CODE_OF_CONDUCT.md
• 漏洞：SECURITY.md（请勿通过公开 issue 报告）

许可证

MIT © Encorp