Microsoft Business Central MCP Server

Microsoft Dynamics 365 Business Central 用の Model Context Protocol (MCP) サーバーです。適切にフォーマットされた API v2.0 呼び出しを通じて、AI アシスタントに Business Central データへの直接アクセスを提供します。

特徴

• ✅ 正しい API URL: 適切な /companies(id)/resource 形式を使用（ODataV4 セグメントなし）

• ✅ インストール不要: npx で実行可能 - 事前インストールは不要

• ✅ Azure CLI 認証: 既存の Azure CLI 認証を活用

• ✅ クライアント資格情報認証: AI エージェント向けのサービス間認証

• ✅ クリーンなツール名: プレフィックスなしで、get_schema、list_items など

• ✅ 完全な CRUD: Business Central レコードの作成、読み取り、更新、削除

インストール

npx を使用（推奨）

インストールは不要です。Claude Desktop または Claude Code で設定してください:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0",
        "BC_COMPANY": "Your Company Name",
        "BC_AUTH_TYPE": "azure_cli"
      }
    }
  }
}

Windows ユーザーへの注意: 上記のように cmd を /c とともに使用して、npx を正しく実行してください。

Smithery を使用

Smithery からインストール:

npx -y @smithery/cli install @knowall-ai/mcp-business-central --client claude

ローカル開発

git clone https://github.com/knowall-ai/mcp-business-central.git
cd mcp-business-central
npm install
npm run build
node build/index.js

設定

環境変数

設定値の取得方法

1. テナント ID: Azure Portal → Azure Active Directory → 概要 で確認

2. 環境: 通常は Production または Sandbox

3. 会社名: Business Central に表示される表示名

URL 形式の例:

https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0

認証

推奨事項: azure_cli 認証を使用してください - セットアップが簡単で、より信頼性が高いです。client_credentials 方式もサポートされていますが、Business Central の Microsoft Entra Applications 設定には既知の構成上の課題があります。詳細は docs/TROUBLESHOOTING.adoc を参照してください。

オプション 1: Azure CLI（推奨）

最も簡単で信頼性の高い認証方法です。既存の Azure CLI ログインを使用します。

前提条件:

• Azure CLI のインストール: https://docs.microsoft.com/cli/azure/install-azure-cli

• ログイン: az login

• アクセスの確認: az account get-access-token --resource https://api.businesscentral.dynamics.com

設定:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_AUTH_TYPE": "azure_cli",
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/Production/api/v2.0",
        "BC_COMPANY": "My Company"
      }
    }
  }
}

オプション 2: クライアント資格情報（サービス間）

ユーザーの操作なしで実行する必要がある自動化システム向けです。この方法は OAuth 2.0 クライアント資格情報フローを使用します。

注意: この方法には既知の構成上の課題があります。Business Central の「Microsoft Entra Applications」設定は複雑で、アプリケーションユーザーの作成が期待どおりに機能しない場合があります。詳細なガイダンスについては docs/TROUBLESHOOTING.adoc を参照してください。

セットアップの概要:

1. Azure アプリ登録を作成:

   • Azure Portal → Azure Active Directory → アプリの登録 に移動

   • 新しい登録を作成（シングルテナント）

   • API アクセス許可を追加: Dynamics 365 Business Central → app_access（アプリケーションのアクセス許可。委任されたアクセス許可ではない）

   • アクセス許可に対する管理者の同意を付与

   • リダイレクト URI を追加: https://businesscentral.dynamics.com/OAuthLanding.htm

2. クライアント シークレットを生成:

   • アプリ登録で、証明書とシークレット に移動

   • 新しいクライアント シークレットを作成し、安全に保存

3. Business Central を設定:

   • Business Central で「Microsoft Entra Applications」を検索

   • + 新規 をクリックし、アプリのクライアント ID を入力

   • 説明を設定（これがアプリケーションユーザー名になります）

   • 状態を「有効」に設定 - 「'[説明]' という名前のユーザーが作成されます」と表示されるはずです

   • アクセス許可セットを追加: D365 BUS FULL ACCESS（推奨）または D365 READ

   • 会社フィールドはすべての会社へのアクセス用に空白のままにする

   • 「同意を付与」をクリック

4. セットアップを確認:

   • アプリケーションユーザーが Business Central のユーザー一覧に表示されるはずです

   • 表示されない場合は、docs/TROUBLESHOOTING.adoc で解決策を確認

参考資料:

• Microsoft: サービス間認証

• Business Central API 認証

利用可能なツール

1. get_schema

Business Central リソースの OData メタデータを取得します。

パラメータ:

• resource（文字列、必須）: リソース名（例: customers、contacts、salesOpportunities）

例:

{
  "resource": "customers"
}

2. list_items

オプションのフィルタリングとページネーションを使用してアイテムを一覧表示します。

パラメータ:

• resource（文字列、必須）: リソース名

• filter（文字列、オプション）: OData フィルター式

• top（数値、オプション）: 返すアイテムの最大数

• skip（数値、オプション）: ページネーションのためにスキップするアイテム数

例:

{
  "resource": "customers",
  "filter": "displayName eq 'Contoso'",
  "top": 10
}

3. get_items_by_field

特定のフィールド値に一致するアイテムを取得します。

パラメータ:

• resource（文字列、必須）: リソース名

• field（文字列、必須）: フィルタリングするフィールド名

• value（文字列、必須）: 一致させる値

例:

{
  "resource": "contacts",
  "field": "companyName",
  "value": "Contoso Ltd"
}

4. create_item

Business Central に新しいアイテムを作成します。

パラメータ:

• resource（文字列、必須）: リソース名

• item_data（オブジェクト、必須）: 作成するアイテムデータ

例:

{
  "resource": "contacts",
  "item_data": {
    "displayName": "John Doe",
    "companyName": "Contoso Ltd",
    "email": "john.doe@contoso.com"
  }
}

5. update_item

既存のアイテムを更新します。

パラメータ:

• resource（文字列、必須）: リソース名

• item_id（文字列、必須）: アイテム ID（GUID）

• item_data（オブジェクト、必須）: 更新するフィールド

例:

{
  "resource": "customers",
  "item_id": "1366066e-7688-f011-b9d1-6045bde9b95f",
  "item_data": {
    "displayName": "Updated Name"
  }
}

6. delete_item

Business Central からアイテムを削除します。

パラメータ:

• resource（文字列、必須）: リソース名

• item_id（文字列、必須）: アイテム ID（GUID）

例:

{
  "resource": "contacts",
  "item_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

一般的なリソース

• companies - 会社情報

• customers - 顧客レコード

• contacts - 連絡先レコード

• salesOpportunities - 営業案件

• salesQuotes - 販売見積

• salesOrders - 販売注文

• salesInvoices - 販売請求書

• items - 製品/サービスアイテム

• vendors - 仕入先レコード

トラブルシューティング

詳細なトラブルシューティングガイドについては docs/TROUBLESHOOTING.adoc を参照してください。以下をカバーしています:

• 認証の問題（401 エラー、トークンの問題）

• client_credentials セットアップの課題と既知の問題

• 会社が見つからないエラー

• 環境固有の設定（Production と Sandbox）

開発

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

ライセンス

MIT

貢献

問題報告とプルリクエストは https://github.com/knowall-ai/mcp-business-central で受け付けています

関連プロジェクト

• MCP 仕様: modelcontextprotocol.io