Dataverse Local MCP

Claude(또는 모든 MCP 클라이언트)를 Microsoft Dataverse / Dynamics 365 환경에 연결하고 평이한 영어로 데이터를 작업하세요 — 레코드 쿼리, 저장된 보기 실행, 테이블과 열 탐색, 행 생성 및 업데이트.

• 항상 하던 방식대로 로그인 — 브라우저에서 여러분의 Microsoft 회사 계정으로, XrmToolBox가 사용하는 것과 동일하게 신뢰받는 로그인을 사용합니다. 별도 설정 없이 바로 작동합니다. 앱 등록도, API 키도, 관리자 설정도 필요 없습니다.

• 두 번째 호출부터 빠릅니다 — 환경의 스키마와 저장된 보기를 배경에서 미리 가져와 로컬에 캐시하므로 메타데이터 질문에 즉시 답합니다.

• 완전한 도구 모음 — OData 쿼리, FetchXML(집계 및 조인), 엔터티 CRUD, 메타데이터 검색이 하나의 서버에 담겨 있습니다.

가이드: 설정 · 사용자 가이드

시작하기

1. Node.js 18 이상을 설치하세요. 아직 설치하지 않았다면.

2. npm 설치 페이지에서 서버를 설치하세요:

npm install -g dataverse-local-mcp

(또는 설치를 건너뛰고 아래 명령어로 npx -y dataverse-local-mcp를 사용하세요.)

3. MCP 클라이언트에 추가하세요 — Claude Desktop에서는 claude_desktop_config.json에 다음을 추가하고 URL을 해당 환경의 URL로 바꾸세요:

{
  "mcpServers": {
    "dataverse": {
      "command": "dataverse-local-mcp",
      "args": ["https://yourorg.crm.dynamics.com"]
    }
  }
}

4. 한 번만 로그인하세요. 도구가 처음 실행되면 브라우저에서 Microsoft 로그인이 열립니다 — 해당 환경의 회사 계정을 선택하세요. 토큰은 ~/.dataverse-mcp/token-cache.json에 캐시되므로 만료될 때까지 다시 입력할 필요가 없습니다. 브라우저가 잘못된 계정으로 로그인된 경우에도 계정 선택기가 항상 표시되어 전환할 수 있습니다.

직접 해보기: MCP 클라이언트에게 whoami 도구를 실행하라고 요청해 보세요 — Dataverse UserId와 OrganizationId를 반환해야 합니다. 그런 다음 "계정의 저장된 보기 나열"이나 "이름(이름) 기준 상위 5개 계정 표시"를 시도해 보세요.

Related MCP server: Dataverse MCP Server

Tools

데이터

스키마

주

환경

안전하게 쓰기

모든 변경 영향을 주는 도구는 기본적으로 미리보기가 먼저 됩니다. confirm: true 없이 호출하면 무엇이 변경될지를 정확히 설명하는 정보만 보여줍니다. — 레코드를 기본 이름(primary name)으로 지정합니다 — 그리고 실제로는 실행하지 않습니다. delete는 추가로 해당 레코드의 현재 필드 값들을 나열하여 무엇이 손실될지 예상할 수 있습니다.

• 한 번에 한 레코드만. update 및 delete는 id 또는 where 필터를 사용하고, 하나 이상의 레코드와 일치하는 것은 거부하며 다중 레코드로 퍼지지 않고 일치하는 후보를 나열합니다.

• 기본적으로 낙관적 동시성. 업데이트 및 삭제에는 레코드의 ETag가 포함되므로, 레코드를 읽은 이후 변경된 내용을 조용히 덮어쓰지 않고 실패합니다. 이 기능을 opt-out 하려면 concurrency: false를 전달해 합니다.

• 페이로드는 전송 전에 검토됩니다. 무명의 열, 해당 작업에 부적합한 열, 옵션 집합의 허용 범위를 벗어난 값, 알 수 없는 @odata.bind 탐색 속성 등의 모든 것은 로컬에서 문제를 지칭하는 메시지로 끝나며, 시스템이 밝혀주지 않는 400 오류를 중심으로 처리하지 않습니다.

• 호출 뒤에는 더 큰 영향이 따라옵니다. Dataverse에서 실제로 많은 작업들이 테이블 쓰기 대신 작업(action)으로 이루어지며, 그 영향은 호출 그 자체가 암시하는 것보다 더 광범위하게 영향 미칩니다. 미리보기는 결과(결과)를 모르고 호출(콜)만을 보여줍니다. 그 영향은 실행하기 전에는 알 수 없습니다.

오류 발생 시 Dataverse가 제공하는 헥스 코드와 메시지가 표시되고, 상태를 인식할 수 있는 형태(권한 거부, 중복 검출, 비즈니스 규칙 또는 플러그인 거부, 동시성, 알 수 없는 열)에는 일반 언어로 해설 접두어가 붙습니다. 그 외의 인식되지 않는 것은 추측하지 않고 원문 그대로 통과시킵니다.

리소스

환경의 전체 OData $metadata(CSDL/EDMX) schema는 MCP 리소스로 제공되며 dataverse://metadata(application/xml, 보통 몇 MB에 달함)에서 접근할 수 있습니다.

캐시 작동 방식

stdio 핸드셰이시약 직후 해당 서버는 백그라운드에서 캐시를 만들기 시작합니다. 시작 시 브라우저를 열지 않습니다. 프리페치는 자동(기본) 인증만 사용하므로 로그인한 토큰이 없으면 먼저 대기하고, 첫 번째 도구 호출에서 로그인 후에 재시도합니다. 그것 어디에서도 차단되지 않습니다 — 콜드 스타트라도 정상 동작하며, 첫 호출이 느릴뿐입니다.

모든 것은 환경 URL이 아닌 OrganizationId를 키로합니다. URL은 바뀌죠, 조직 ID는 바뀌지 않아서입니다:

~/.dataverse-mcp/
  token-cache.json
  environments/
    index.json                 # host -> organizationId, so a warm start needs no network
    <organizationId>/
      config.json              # url, friendly name, mode, storage, scope, sampling
      schema.json              # cached metadata          } these two follow
      schema.fingerprint       # hash for drift detection } your storage choice
      annotations.md           # your documentation       }
      metadata.xml             # the $metadata resource   } always local:
      saved-queries.json       #                          } large, derived, cheap to refetch

config.json 및 index.json은 항상 로컬에 위치합니다. 저장소 설정 자체를 담고 있기 때문에 그 설명하는 대상인 백엔드에는 존재할 수 없습니다.

범위. 모든 테이블에서는 비용이 낮은 이름 수준의 요약만 캐시됩니다. 전체 열 및 관계 정보는 모든 사용자 정의 테이블과 함께 기본 제공 테이블의 허용 리스트(기본은 Field Service 및 핵심 영업/서비스)까지, 최고 수와 maxFullTables의 상한에 따라 캐시됩니다. 그 이외는 지연(lazy) 방식으로 가져와서 해당 도구가 처음 다루는 시점에 병합됩니다.

샘플링(행)의 기본값은 off입니다. 이 기능을 환경(environment) 단위로 켜면, 캐시에 각 열에 대해 채움율과 최대 20개 행에서 최대 5개의 예를 값도 기록됩니다. 이는 설명이 비어 있는 테이블에 가장 유용한 정보입니다. 실제 데이터를 읽기 때문에 기본적으로 선택(opt-in) 방식이며, 개인정보로 판단되는 형식이나 열형식의 유형의 열은 명시적으로 허용하지 않는 한 절대로 표본 샘플링하지 않습니다.

주석(니)

Dataverse의 설명은 비어 있는 경우가 많습니다. 환경의 형태 자체에도 뭐가 대부분의 의미를 담고 있지만, 그것 빼고 나머지는 재도출 대신 계속해서 쌓아 둘 만한 인간의 지식입니다. 주석(annotation)은 environments/<organizationId>/annotations.md 에서 일반 markdown으로 관리됩니다 — 사람이 직접 판독 가능하고 diff를 만들 수 있으며, 프로젝트 저장소에 검증가능한 커밋내용으로 안전합니다.

## rsm_cipscenariocandidate

Candidate records for capital improvement plan scenario modelling. Populated by
the scenario engine, not by users directly.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: human_

### rsm_scenariotype

Picklist. 1 = replacement, 2 = rehabilitation, 3 = deferral.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: inferred_ · _provenance: human_

각 주석에는 두 가지 독립 필드가 있습니다. Confidence(신뢰도) 는 담당자가 직접 확인했을 때만 confirmed로 상태를 표시하며, 기계 또는 도구가 돌려낸 결과는 항상 inferred입니다 — 기본적으로 Dataverse의 설명(description) 필드에 다시 기록되지 않는 이유가 바로 이 때문입니다. Provenance(기원) 는 human, preflight, velocity, model 중 하나이며, 다시 스캔할 때 덮어쓰기 동작을 결정합니다: 수정 대상자(작성자)는 이전의 자신의 메모를 자유로이 교체할 수 있고, 사람이면 무엇이든 교체할 수 있습니다. 그러나 그 밖의 다른 것은 덮어쓰지 않습니다. 다시 스캔 결과가 사용자가 직접 작성 것과 모순될 때는 어느 한쪽이 조용히 이기지 않고, 두 가지 모두 유지하면서 사람이 정리하라는 표시를 남깁니다.

도구에 생성된 annot는 인용 블록(blockquote)으로 보여 주어, 사람이 직접 만든 것이 한눈에 구분됩니다:

### rsm_scenariotype

> No plugins are registered on this column.

_author: preflight_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: preflight_

공유하기. export_annotations은 파일을 원하는 위치에 내보내 합니다. import_annotations은 마크다운 파일을 받아들입니다. 프론트 매터에는 organizationId가 들어 있으며, 다른 조직으로 가져오는 작업은 보드에서 거부—가 되며 절대로 병합하지 않습니다. 양쪽 모두 동일한 대상에 각자 다른 텍스트를 주열한 경우 어느 하나가 묵인하게 이기는 일이 없이 둘 다 유지되며 처리를 위해 표시됩니다.

드리프트(drift). 캐시 시점에 스키마에서 지문(핑거프린트)을 캡처합니다. 이 지문이 변경되면 각 annotation을 대상으로 현재 valid, changed (주석 아래의 유형 또는 옵션 셋이 변경됨), 또는 orphaned (대상이 존재하지 않음)으로 판정됩니다. 알림은 연결 시 간단한 요약으로 기록되고, 구체적 경고는 describe_table 내에서 인라인으로 반복 부여됩니다. 그리고 그 무엇도 자동으로 지우지 않습니다.

모드. 각 환경은 특권(권한)에서 추론되지 않고 항상 명시적으로 설정합니다. — 특권은 의도보다 더 광범위한 경우가 많기 때문입니다. ‘consumer’(기본값)는 주석을 주석을 사용자 로컬에만 유지하고 메타 데이터를 전혀 쓰지 않습니다. — 메타데이터를 쓸 수 없음 즉 쓰지 않습니다(산출). ‘maker’는 확인된(confirmed) 데이터 정보 주석을 Dataverse 설명 자체로 프로모션하는 것을 추가 합니다.

Dataverse 문 설명 도입

환경의 스키마 소유자라면 확인된 주석을 실제 Dataverse 설명으로 만들 수 있습니다. 이 단계는 의도적으로 번잡하게 설계되어 있으며, 불편함을 줄이기 편의를 줄이는 것을 권장하지 않습니다: 필요한 조건은 maker 모드와 확인된 ‘confirmed’ 주석(추론러는 거부), 주석 위 관의 상 해결되지 않은 충돌 없고, 호출당 하나의 대상 목록, 표시된 미리보기 내용의 확인 후 명시 적 확인 동의가 있어야 합니다.

작성된 텍스트에는 [dataverse-mcp] 마커와 출처 및 날짜가 접두사로 붙습니다. 그 마커가 핵심입니다. 마커가 없으면 승격된 메모는 6개월 후 사람이 작성한 설명과 구별할 수 없게 되고, 합리적인 추측으로 읽히던 것이 사실로 읽히기 시작합니다.

승격은 메타데이터 쓰기입니다. 활성 솔루션 계층에 비관리형 사용자 지정을 생성하며, 이는 관리형 구성 요소에 대한 이후 업데이트를 가릴 수 있고, 설명이 UI에 나타나기 전에 게시가 필요할 수 있습니다. 미리보기는 확인하기 전에 이 모든 것을 알려주며, 도구는 이를 실행 취소할 수 없습니다.

문서가 저장되는 위치

기본적으로 모든 것은 ~/.dataverse-mcp 아래에 있습니다. set_storage로 다른 위치를 지정하면 주석 및 메타데이터 캐시가 모두 따라갑니다. 이들은 환경별로 항상 함께 이동합니다.

파일 기반 종류는 하나의 구현입니다. Obsidian 볼트, OneDrive 동기화 폴더, Basic Memory 디렉터리는 모두 그냥 폴더이며, git은 커밋 단계를 추가합니다. 각 환경은 고유한 하위 폴더(dataverse-mcp/<friendlyName>-<orgId prefix>)를 가지므로 공유 볼트나 저장소에 여러 환경을 충돌 없이 보관할 수 있습니다.

Notion은 NOTION_TOKEN 환경 변수의 내부 통합 토큰이 필요합니다. 파일이 아닌 MCP 클라이언트 구성에 설정하세요. 또한 상위 페이지의 notionPageId가 필요하며, 이는 통합과 공유되어야 합니다. 각 Markdown 줄은 하나의 단락 블록이 되므로 문서가 정확히 그대로 유지되며 Notion에서 읽고 편집할 수 있습니다. Notion은 파일 저장소가 아닌 문서 저장소이므로 Notion을 선택하면 스키마 캐시는 로컬 디스크에 남고 주석은 Notion에 저장됩니다.

저장소를 전환해도 기존 데이터는 복사되지 않습니다. 이전하려면 먼저 export_annotations를 실행하세요.

0.3.x에서 업그레이드

list_entities와 describe_entity는 list_tables와 describe_table로 대체되었습니다. 이 새 도구는 새 캐시를 읽고 주석과 드리프트 경고를 통합합니다. 0.3.x 캐시 디렉터리 ~/.dataverse-mcp/cache/<host>/는 더 이상 읽히지 않으므로 삭제해도 됩니다. 새 캐시는 첫 연결 시 자동으로 다시 빌드됩니다. 토큰 캐시는 그대로이므로 다시 로그인할 필요가 없습니다.

빌드 사양(기여자용)

목표

Dataverse Web API와 직접 통신하는 독립형 MCP 서버를 구축합니다. Web API를 직접 사용하면 서버를 작고 의존성이 적게 유지할 수 있으며, 머신과 테넌트 전반에서 가장 폭넓게 작동하는 로그인 흐름을 사용할 수 있습니다. 엄격한 조건부 액세스 정책이 있는 테넌트도 포함됩니다. TypeScript, 로컬 Node 호스트, 새로운 앱 등록 불필요.

이 인증 방식의 이유

이 서버는 XrmToolBox와 Microsoft의 XRM Tooling 샘플과 동일한 검증된 인증 패턴을 사용합니다. Microsoft가 제공하고 사전 동의된 공용 클라이언트에 루프백 리디렉션을 사용하며, 표준 MSAL 인증 코드 + PKCE 흐름으로 구동됩니다. 테넌트가 이미 신뢰하는 일반적인 브라우저 로그인입니다. 모든 OS에서 실행되며, 디바이스 코드 흐름을 차단하는 조건부 액세스 정책을 충족하고 OS 수준 브로커가 필요 없습니다. XrmToolBox가 연결되는 모든 곳에서 이 서버도 연결됩니다.

Client ID: 51f81489-12ee-4a9e-aaae-a2591f45987d
Redirect URI: http://localhost
Authority: https://login.microsoftonline.com/common
Scope: <environmentUrl>/.default

이것은 user_impersonation 위임 권한을 가진 Microsoft 다중 테넌트 샘플 앱으로, 관리자 동의가 필요 없습니다. XrmToolBox가 테넌트에서 이미 성공적으로 연결된다면, 이 동일한 클라이언트 ID가 해당 테넌트의 조건부 액세스를 이미 통과한다는 것이 입증된 것입니다.

v1의 비목표

• 사용자 지정 Entra 앱 등록 없음(위의 잘 알려진 클라이언트 ID 사용)

• 서비스 주체 / CI 인증 없음(대화형 사용자 인증만)

저장소 구조

packages/
  core/                    @dataverse-platform/core — shared library, private
    src/
      index.ts             public surface
      auth.ts              MSAL interactive + silent acquisition
      cache.ts             atomic read/write helpers
      paths.ts             ~/.dataverse-mcp layout
      environment.ts       per-environment config, OrganizationId resolution
      dataverseClient.ts   Web API calls
      writes.ts            preview/confirm, validation, single-record resolution
      promotion.ts         annotation -> Dataverse description, maker mode only
      errors.ts            Dataverse error translation
      store.ts             $metadata + saved-view warm cache
      metadata/            schema cache: types, fingerprint, build, sampling
      annotations/         markdown model, store, drift detection
      storage/             backends: directory/git presets, Notion
  mcp-server/              dataverse-local-mcp — published to npm
    src/
      server.ts            MCP wiring
      tools/               tool definitions and formatters
    build.mjs              esbuild bundle (inlines core)
    prepack.mjs            stages README/LICENSE for packing
package.json               npm workspaces root
tsconfig.base.json

평가 도구(powerpreflight, velocity)는 추가 packages/*로 포함되며, MCP 서버를 거치지 않고 코어를 라이브러리로 직접 호출합니다.

종속성

npm install          # installs every workspace
npm run typecheck    # tsc -b across packages
npm run build        # core via tsc, mcp-server bundled via esbuild
npm run clean        # removes dist and tsbuildinfo

런타임 종속성은 @azure/msal-node, @modelcontextprotocol/sdk, open입니다. HTTP 호출은 Node의 내장 전역 fetch를 사용하므로(따라서 Node ≥ 18 요구 사항) HTTP 클라이언트 종속성이 없습니다.

1단계 — 인증 모듈(src/auth.ts)

acquireTokenInteractive를 사용하여 토큰을 획득하고 캐시합니다. 이 함수는 자체 루프백 리스너를 시작하므로 수동 HTTP 서버가 필요 없습니다.

• 클라이언트 ID 51f81489-12ee-4a9e-aaae-a2591f45987d, 기관 https://login.microsoftonline.com/common

• 범위 <environmentUrl>/.default

• 토큰 캐시는 ~/.dataverse-mcp/token-cache.json에 저장

• 캐시에서 먼저 자동 획득을 시도하고, 실패 시 대화형으로 폴백(open 패키지로 시스템 브라우저를 엶; 대신 URL을 출력하려면 DATAVERSE_MCP_NO_OPEN=1 설정)

• 대화형 로그인은 항상 계정 선택기를 표시하므로(prompt: select_account) 브라우저 SSO가 잘못된 계정의 토큰을 조용히 돌려줄 수 없습니다

• 동시 대화형 로그인은 환경별로 중복 제거됩니다. 병렬 요청은 하나의 브라우저 창을 공유합니다

• silentOnly 모드는 캐시 프리페치를 뒷받침합니다. 브라우저를 여는 대신 예외를 던지므로 백그라운드 작업이 클라이언트 시작을 방해하지 않습니다

2단계 — Dataverse Web API 클라이언트(src/dataverseClient.ts)

Dataverse Web API(/api/data/v9.2/)에 대한 얇은 래퍼로, Authorization: Bearer, OData-MaxVersion: 4.0, OData-Version: 4.0 헤더를 보내고 Retry-After에 따라 429/503을 재시도하므로 대량 메타데이터 빌드가 서비스 보호 한도를 넘겨도 견딜 수 있습니다. whoAmI(), 일반 get(), 레코드 생성/업데이트/삭제(PATCH는 If-Match: *를 보내므로 업데이트가 조용히 upsert되지 않음), FetchXML 쿼리, 저장된 보기(savedquery + userquery, @odata.nextLink를 따라감), 원시 $metadata EDMX, EntityDefinitions를 통한 메타데이터 읽기를 포함합니다.

두 가지 Dataverse 제약이 메타데이터 호출을 결정합니다. EntityDefinitions는 $top과 $orderby를 거부하고($select와 $filter는 허용), DisplayName/Description/RequiredLevel은 스칼라가 아닌 객체로 반환되므로 레이블은 UserLocalizedLabel.Label에서 추출됩니다. 옵션 집합은 캐스트가 필요합니다. 클라이언트는 EnumAttributeMetadata 기본 캐스트를 먼저 시도하고(선택 목록, 상태, 상태 코드, 다중 선택에 대해 한 번의 호출) 지원되지 않는 경우 구체적인 캐스트로 폴백합니다.

3단계 — MCP 서버 진입점(src/server.ts)

위의 도구 섹션에 나열된 도구와 dataverse://metadata 리소스를 등록하고, 전송이 연결된 후 백그라운드 캐시 프리페치를 시작합니다. 표준 @modelcontextprotocol/sdk Server 클래스를 stdio 전송과 함께 사용하며, 이는 @microsoft/dataverse mcp 자체가 실행되는 방식과 동일합니다. 환경 URL은 첫 번째 CLI 인수로 전달됩니다.

4단계 — 첫 테스트

npm run build
node dist/server.js https://yourorg.crm.dynamics.com

예상 동작: 대화형 로그인을 위해 시스템 브라우저가 한 번 열리고, 토큰이 ~/.dataverse-mcp/token-cache.json에 캐시되며, 이후 실행에서는 캐시된 토큰을 조용히 재사용합니다. whoami 도구를 호출하고 반환된 UserId/BusinessUnitId를 확인하여 성공을 확인하세요. 첫 로그인 후 백그라운드 프리페치가 ~/.dataverse-mcp/cache/<org-host>/에 metadata.xml, entities.json, saved-queries.json을 채웁니다. 이후 실행에서는 해당 캐시에서 메타데이터 및 저장된 보기 도구를 제공합니다.

5단계 — Claude Desktop 구성

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/full/path/to/DataVerseLocalMCP/dist/server.js", "https://yourorg.crm.dynamics.com"]
    }
  }
}