business-central-mcp-server

Dynamics 365 Business Central(온라인) 데이터를 MCP 클라이언트(Claude Code, Claude Desktop 등)에 노출하는 MCP 서버입니다. 환경, 회사, 표준 v2.0 API 또는 사용자 지정 AL API를 통해 접근 가능한 모든 엔터티를 다룹니다.

api.businesscentral.dynamics.com과 통신하며, 동일한 대상에 대한 Entra 토큰을 사용합니다. 위임된(delegated) 인증(대화형 / 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(기본 64MiB)를 초과하는 다운로드는 아무것도 쓰기 전에 거부됩니다.

쓰기(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와 해당 토큰을 사용한 두 번째 호출만 삭제를 수행하며, 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 참조.