business-central-mcp-server

Dynamics 365 Business Central (オンライン) のデータを MCP クライアント (Claude Code、Claude Desktop など) に公開する MCP サーバーです。環境、会社、および標準の v2.0 API またはカスタム AL API から到達可能な任意のエンティティを扱います。

api.businesscentral.dynamics.com に対して、同じ対象者向けの Entra トークンを使用して通信します。委任認証 (interactive / cli / azure-powershell) では、アプリ登録も管理者の同意も不要です。サインインしたユーザーとして動作し、そのユーザーの Business Central 権限セットに制約されます。

ツール

読み取り (常時有効)

AL 拡張機能から公開されたカスタム API は、api_route: "{publisher}/{group}/{version}" を使用してどこからでもアクセスできます。

ドキュメントのエクスポート

Business Central は、生成されたドキュメントやアップロードされたファイルを JSON フィールドではなく OData メディアストリームとして提供します。export_file はそれらのバイトを取得してディスクに書き込みます。ツールはコンテンツではなくパス、サイズ、SHA-256 を返すため、大きな PDF がモデルのコンテキストに入ることはありません。BC からの読み取りのみですが、ローカルファイルシステムに書き込むため、書き込み層に登録されます。使用するには BC_MCP_MODE=write を設定してください。

まずメディアリンクを確認してからダウンロードしてください:

// get_entity — confirm the invoice has a renderable PDF
{ "entity_set": "salesInvoices", "record_id": "<guid>", "sub_path": "pdfDocument" }

// export_file — write the bytes out
{
  "entity_set": "salesInvoices",
  "record_id": "<guid>",
  "sub_path": "pdfDocument/pdfDocumentContent",
  "output_path": "./exports"
}

便利なメディアパス: salesInvoices、salesCreditMemos、purchaseInvoices の pdfDocument/pdfDocumentContent、attachments の content、items と employees の picture。

output_path はファイルまたはディレクトリを指定できます。ディレクトリ (または末尾の区切り文字) を指定すると、ファイル名はレコードと検出されたコンテンツタイプから決定されます。完全に省略すると BC_EXPORT_DIR にフォールバックし、次に作業ディレクトリにフォールバックします。overwrite: true を渡さない限り既存ファイルは上書きされず、max_bytes (デフォルト 64 MiB) を超えるダウンロードは、何も書き込む前に拒否されます。

書き込み (BC_MCP_MODE=write)

すべての書き込み呼び出しは、タイムスタンプ、ツール、ターゲット、呼び出し元 ID とともに stderr に監査ログとして記録されます。これらは実際の ERP データを変更します — ドキュメントを転記すると、簡単には削除できない元帳エントリが作成されます。実験中は BC_DEFAULT_ENVIRONMENT をサンドボックスに向けてください。

破壊的操作 (BC_MCP_MODE=write かつ BC_MCP_ALLOW_DELETE=true)

破壊的層はデフォルトでオフです。有効にすると、各呼び出しはまず計画になります。dry_run=true (デフォルト) は、削除されるレコードと使い捨ての confirm_token を返します。dry_run=false とそのトークンを使った 2 回目の呼び出しのみが、If-Match etag で保護された削除を実行します。

Related MCP server: Microsoft Business Central MCP Server

Claude Desktop へのインストール

最新リリース から business-central-mcp-server-<version>.mcpb をダウンロードして開きます。これでインストールは完了です。クローンも npm install も、マシン上の Node も不要です。Claude Desktop には独自の Node ランタイムが同梱されており、バンドルには依存関係が含まれています。

インストールダイアログでは次の項目を入力します:

デフォルトの interactive サインインでは、クライアント ID とシークレットは空白のままにします。サーバーはパブリックな Azure CLI クライアントにフォールバックし、ブラウザを開き、サインインしたユーザーとして、そのユーザーの Business Central 権限セットの下で動作します。アプリ登録や管理者の同意を準備する必要はありません。

ブラウザのプロンプトは Claude Desktop を再起動するたびに表示されます。トークンはメモリ内にのみ保持されます。永続化するには、ネイティブの資格情報キャッシュモジュールとプラットフォームごとの個別のバンドルが必要になります。

バンドルを自分でビルドする

npm ci
npm run build:mcpb    # writes dist/business-central-mcp-server-<version>.mcpb
npm run verify:mcpb   # unpacks it and boots the server the way Desktop would

build:mcpb は、マニフェストのバージョンが package.json と一致しない場合、または宣言されたツールリストがサーバーが実際に登録するものと一致しない場合、バンドルの生成を拒否します。

セットアップ (Claude Code およびその他の MCP クライアント)

cd business-central-mcp-server
npm install

MCP クライアントに登録します。.claude.json のエントリ例 (委任認証、読み取り専用):

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/business-central-mcp-server/index.js"],
      "env": {
        "AZURE_TENANT_ID": "<your-entra-tenant-id>",
        "BC_AUTH_MODE": "interactive",
        "BC_MCP_MODE": "read",
        "BC_DEFAULT_ENVIRONMENT": "Production"
      }
    }
  }
}

レコードの作成/更新とバインドされたアクションの呼び出しを許可するには、"BC_MCP_MODE": "write" を設定します。削除も許可するには、"BC_MCP_ALLOW_DELETE": "true" を追加します。

単一の会社で作業し、毎回の呼び出しで company_id を省略したい場合は、BC_DEFAULT_COMPANY_ID を list_companies の値に設定します。

呼び出しで output_path が省略された場合に export_file が書き込む場所を選択するには、BC_EXPORT_DIR を設定します。

サポートされているすべての認証モードを含む環境変数の完全なリストについては、.env.example を参照してください。

認証に関する注意

• 委任 (推奨): interactive、device-code、cli、または azure-powershell。アプリ登録は不要です。呼び出し元はサインインしたユーザーとして動作し、そのユーザーの BC 権限セットと会社アクセスに制限されます。

• サービスプリンシパル: 非対話型ですが、データプレーンが受け入れる前に、SP を Business Central 内の Entra アプリケーションとして登録する必要があります (Entra アプリケーションページで権限セットを割り当てます)。

• list_environments は管理センターの検出 API を使用するため、BC 管理センターへのアクセスがさらに必要です。他のツールは、環境名を直接渡せばそれなしで動作します。

要件

• 対象テナントで Business Central のライセンスを持つ Entra ID。

• ソースから実行する場合は Node.js >= 20。Claude Desktop バンドルにはそのような要件はありません。Desktop がランタイムを提供します。

ライセンス

MIT — LICENSE を参照してください。