NULA.BG

nulabg-mcp

会計プラットフォーム nula.bg 向けの MCP サーバーです。nula.bg API キーを使って、Claude やその他の AI アシスタント（Claude Desktop、Claude Code、Cursor、VS Code…）から請求書、購入、OCR、顧客、在庫、銀行にアクセスできます。

非公式クライアントです。 このプロジェクトは nula.bg とは無関係です。公開されている REST API を使用します。

🇬🇧 英語版： nula.bg（ブルガリアのクラウド会計プラットフォーム）向けの MCP サーバーです。API キーを使って、請求書、OCR による請求書、顧客、在庫、銀行フィード、派生レポートにアクセスできます。デフォルトでは読み取り専用です。Claude Desktop に .mcpb バンドルをインストールするか、NULA_API_KEY を設定して npx -y nulabg-mcp を実行してください。この README の残りの部分は、プラットフォームとその書類、ユーザーがブルガリア語を使用するため、ブルガリア語で記載されています。モデルに表示されるツールの説明は英語です。どちらの言語でも、Issue やプルリクエストを歓迎します。

できること

モジュール（toolset）	ツール	内容
core	nula_lookup_company	統一識別コードまたは VAT 番号で企業を照会（商業登記簿／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	購入（VAT 法第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	NRA への申告のステータス（提出なし）
noi（無効）	nula_noi_documents, nula_noi_get_document	NOI 向け書類（付属書9／10／11）

変更を許可した場合は21個のツール、デフォルトの読み取り専用モードでは13個、nra と noi を有効にすると25個です。 複数の会社がある場合は、nula_list_companies も表示されます。

さらに、以下もあります。

• プロンプト： issue-invoice、process-receipts、month-end-review、collect-overdue。
• リソース： VAT 0％の根拠、議事録の根拠、すべての enum 値、請求書の PDF。

リクエストの例：

• 「統一識別コード 123456789 の会社に、VAT 抜きで1時間60 €のコンサルティングを10時間分、15日以内の銀行振込で支払う請求書を発行して。」
• 「~/Documents/Фактури/Септември 内のすべての PDF を購入としてアップロードして、認識された内容を見せて。」
• 「30日を超えて未払いの顧客は？」
• 「9月の銀行口座への入金と未払いの請求書を照合して。」

インストール

nula.bg アカウントから生成した nula.bg の API キーが必要です。このキーを使うと会社のデータにアクセスできるため、パスワードと同じように保管してください。

🔒 デフォルトではサーバーは読み取り専用です。 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）

• 2026年9月26日に実際のアカウントで検証済みです。 13個すべての読み取りツールと書き込み操作（発行、編集、支払い済み／送信済み、PDF、メール）は、実データで動作します。応答形式はdocs/research/nula-api-analysis.md §8–§9に記載されています。動作しないのは削除だけです。詳細は以下をご覧ください。OCR、НАП、НОИは、キーにアクセス権がないためテストしていません。
• OCR、НАП、НОИには、会社へのアクセス権を持つキーが必要です。 プロフィールで作成したキーでは、これらのエンドポイントは403「This token is not scoped to a team you can access」を返します。その他のモジュールは動作します。
• 品目： 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となるため、削除できません。書類はウェブアプリから手動で削除するか、クレジットノートで処理します。このツールは失敗するリクエストを送信する代わりに、事前に確認します。
• 仕入れ時のコールバックURL。 createBillにはcallback_urlが必要です。デフォルトではnula.bg自体のアドレスが指定されるため、データが第三者に送信されることはありません。独自のWebhookがある場合は、NULA_BILL_CALLBACK_URLを設定してください。
• 未対応のAPI操作。 nula.bg APIには、取引先の作成または編集（顧客は最初の請求書と同時に自動作成されます）、IDによる請求書のGET、VATおよび支払いに関する照会機能がありません。

開発

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タグを作成します。GitHub Actionsがprovenance付きでnpmに公開し、.mcpbをGitHub Releaseに添付して、MCP Registryを更新します。

貢献

Issueやプルリクエストを歓迎します。ブルガリア語または英語でお寄せください。特に役立つのは実際のAPIとの不一致（フィールド名や型。実データは含めないでください）の報告です。公式ドキュメントには、ほぼリクエストしか記載されていないためです。

• プロジェクトへの参加方法：CONTRIBUTING.md
• コミュニティのルール：CODE_OF_CONDUCT.md
• 脆弱性：SECURITY.md（公開Issueでは報告しないでください）

ライセンス

MIT © Encorp