xrm-mcp

A minimal MCP server that gives AI coding agents (Claude Code, GitHub Copilot, Codex CLI, Cursor, Gemini CLI) clean read + careful write access to Microsoft Dataverse / XRM environments via the Dataverse Web API v9.2.

Why this exists: Microsoft ships its own Dataverse MCP server, but it requires Power Platform admin setup, Managed Environments, and Copilot Credits per call. xrm-mcp is a drop-in alternative that works with any Dataverse environment using your existing Azure CLI or Microsoft account. Read more →

Features

• No Microsoft MCP billing — calls the Dataverse Web API directly, no Copilot Credits consumed

• No admin toggles — works with any Dataverse environment you can log into

• No Managed Environment required — standard environments work fine

• No per-environment setup — org_url is a parameter on every tool call

• Multi-tenant by design — connect to multiple orgs in the same session, with per-environment identity caching so switching between tenants doesn't require re-authenticating each time

• Azure CLI + MSAL auth — tries az first, falls back to interactive device flow

• 8 MCP tools — ping, find/list tables, describe schema, query, create, update, upsert

Related MCP server: dataverse-mcp-server

Installation

For uv, pipx, virtual environments, pinned tags, and client setup, see the installation guide.

Install via pipx (recommended):

pipx install git+https://github.com/jukkan/xrm-mcp.git

Or via pip:

pip install git+https://github.com/jukkan/xrm-mcp.git

Usage

Configuring your AI agent

Add xrm-mcp to your agent's MCP configuration.

Claude Desktop / Claude Code (~/.claude/claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "xrm-mcp": {
      "command": "xrm-mcp"
    }
  }
}

GitHub Copilot (VS Code) — add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "xrm-mcp": {
      "type": "stdio",
      "command": "xrm-mcp"
    }
  }
}

Once configured, pass your environment URL with every request and the agent takes it from there:

"Show me all project records from https://myorg.crm4.dynamics.com created in the last 30 days"

Running the server manually

xrm-mcp

The server uses FastMCP and communicates over stdin/stdout (stdio transport).

Authentication

XRM MCP attempts authentication in the following order:

1. Azure CLI — if az is available and logged in

2. MSAL device flow — interactive browser-based login

Tokens are cached at ~/.xrm-mcp/cache.json.

If you work across multiple tenants (e.g. your own production environment, demo environments, and customer tenants), XRM MCP remembers which identity last worked for each org_url in ~/.xrm-mcp/identity_cache.json and prefers it on the next call — so switching tenants doesn't depend on which az account happens to be active. If a call gets a 401/403, that org's cached identity is cleared automatically and the error message tells you to just retry, which re-discovers a working identity.

To re-authenticate, delete ~/.xrm-mcp/cache.json or use az login. To reset which identity is used for a specific org, delete its entry from ~/.xrm-mcp/identity_cache.json.

Testing authentication manually

python -m xrm_mcp.auth https://yourorg.crm4.dynamics.com

MCP Tools

Read Tools

ping(org_url)

• Verify connectivity and authentication to a Dataverse environment

• Returns: status, org_url, user_id, business_unit_id, org_id, auth_method, tenant_id

• Call this first when connecting to a new environment; auth_method/tenant_id let you confirm which identity answered the call

find_table(org_url, name)

• Search for a table by display name or partial logical name

• Use when the user says "hour entries" and you need the exact logical name

• Returns all matching tables sorted by exact display name match first

list_tables(org_url, search="", custom_only=True, prefix="", exclude_ms_prefixes=True)

• List Dataverse tables, defaulting to custom entities only

• custom_only=True — only return custom entities (default)

• prefix="na_" — filter to a specific publisher prefix

• exclude_ms_prefixes=False — include Microsoft solution tables (msdyn_, adx_, etc.)

• Returns: logical_name, display_name, entity_set_name, is_custom, description

describe_table(org_url, table)

• Get columns, types and descriptions for a Dataverse table

• Call this before querying when you need exact column names for $select or $filter

• Returns: table_name, columns with metadata

query_records(org_url, table, select="", filter="", top=100, orderby="")

• Query records from a table using OData filter syntax

• Returns: {count, records}

• Top is capped at 5000

• select is validated against real column names before querying; an invalid column raises a clear error naming it, instead of silently returning every column

Write Tools

create_record(org_url, table, data)

• Create a single record

• Returns: {id}

update_record(org_url, table, record_id, data)

• Update specific fields on an existing record

• Returns: {success, id}

upsert_record(org_url, table, alternate_key, alternate_value, data)

• Create or update a record using an alternate key (for sync/import scenarios)

• Returns: {success, alternate_key, alternate_value}

Example Usage

See CLAUDE.md for detailed agent usage examples and WHY.md for how this compares to Microsoft's own Dataverse MCP server.

Requirements

• Python 3.10+

• Azure CLI (optional, for az authentication)

• Access to a Dataverse / Dynamics 365 environment

Dependencies

• fastmcp >= 3.0, < 4

• msal >= 1.28.0, < 2

• httpx >= 0.27.0, < 1

Version 0.2.0 moved from FastMCP 2.x to FastMCP 3.x. Existing installs need to be reinstalled (for example pipx reinstall xrm-mcp or uv tool install --force ...) so the new FastMCP version is resolved.

Development

Clone the repository:

git clone https://github.com/jukkan/xrm-mcp.git
cd xrm-mcp

Install in development mode:

pip install -e ".[dev]"

Run the tests (no Dataverse environment or credentials required):

pytest

License

MIT

Contributing

Contributions welcome! Please open an issue or pull request.