Microsoft Business Central MCP Server

Microsoft Dynamics 365 Business Central용 MCP(Model Context Protocol) 서버입니다. 올바르게 포맷된 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 참고 사항: 위와 같이 npx를 제대로 실행하려면 cmd를 /c와 함께 사용하세요.

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 응용 프로그램 설정과 관련하여 알려진 구성 문제가 있습니다. 자세한 내용은 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 응용 프로그램" 설정이 복잡할 수 있으며 응용 프로그램 사용자 생성이 예상대로 작동하지 않을 수 있습니다. 자세한 지침은 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 응용 프로그램" 검색

   • + 새로 만들기를 클릭하고 앱의 클라이언트 ID 입력

   • 설명 설정 (이 값이 응용 프로그램 사용자 이름이 됨)

   • 상태를 "사용"으로 설정 - "'[Description]'이라는 사용자가 생성됩니다"라는 메시지가 표시되어야 함

   • 권한 집합 추가: 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 vs 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