Dataverse MCP Server

An MCP server that gives AI agents structured access to Microsoft Dataverse — query records, bulk upsert data, inspect metadata, manage schema, analyze component dependencies, manage model-driven app forms, views, and apps, administer security roles, teams, and users, audit user access, manage plug-in trace logging, manage custom APIs, and explore Power Platform environments.

Built with FastMCP, httpx, and the Dataverse OData v4.0 Web API. Communicates over stdio and works with Claude, GitHub Copilot, and any MCP-compatible client.

Quick Start

1. Install uv

pip install uv

2. Configure — add to your MCP client config:

Claude (claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "dataverse-mcp": {
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "dataverse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

3. Sign in

On first use the server opens a browser for interactive sign-in. The session is cached and reused across restarts (see DATAVERSE_TOKEN_CACHE_PERSIST), so you are not prompted again while the token is valid.

That's it. Your AI agent can now query your Dataverse environments.

Prefer your existing Azure CLI session instead? Set DATAVERSE_AUTH_TYPE to azure_cli and run az login.

Installation

Install uv

uvx is provided by uv. Install it first if you don't have it:

pip install uv

Run from PyPI (recommended)

uvx dataverse-mcp

uvx downloads and runs the package in an isolated environment — no virtual environment management required.

Run from a local checkout

git clone https://github.com/ryanmichaeljames/dataverse-mcp.git
cd dataverse-mcp
uv sync

This creates .venv. Use the local source MCP config shown in Client Setup to point your client at it. No build step required — code changes are picked up on the next server start.

Configuration

Set these in the env block of your MCP server entry. This project does not use a .env file.

[!WARNING] Leaving DATAVERSE_WHITELIST unset is risky. Tools accept a dataverse_url per call, and the server mints a bearer token for whatever environment is supplied. Without a whitelist, a compromised or misbehaving agent can direct your credentials at any Dataverse environment. Set DATAVERSE_WHITELIST to the specific environment hostnames you intend to use so the server rejects everything else. On shared or multi-tenant hosts, also set DATAVERSE_REQUIRE_WHITELIST=true so the server fails closed rather than minting tokens when the whitelist is accidentally left empty.

Authentication

[!NOTE] Interactive auth persistence. When DATAVERSE_TOKEN_CACHE_PERSIST=true (the default), the MSAL token cache is stored on disk using your OS secret store (Windows DPAPI, macOS Keychain, Linux libsecret). On headless Linux without libsecret, the first token acquisition will fail fast with an error. Set DATAVERSE_TOKEN_CACHE_ALLOW_UNENCRYPTED=true to permit a plaintext cache on those hosts, and see the security warning for that variable above.

[!NOTE] Running multiple tenants/accounts at once. The default cache and sidecar filenames are shared per host, so two interactive sessions signed in to different tenants/accounts would overwrite each other's pinned account. Give each session a distinct DATAVERSE_TOKEN_CACHE_PROFILE (e.g., prod, dev) to keep their caches and AuthenticationRecord sidecars separate.

Example: two tenants side by side

Register two server entries, each with its own DATAVERSE_TOKEN_CACHE_PROFILE. The profile is a tenant-wide cache key — each entry signs in once (its own browser prompt) and then restarts silently as its own account, while tools still receive the specific dataverse_url per call. The profiles never collide.

Claude (claude_desktop_config.json or .claude/settings.json):

{
  "mcpServers": {
    "dataverse-prod": {
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive",
        "DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
      }
    },
    "dataverse-dev": {
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive",
        "DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
      }
    }
  }
}

GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "dataverse-prod": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive",
        "DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
      }
    },
    "dataverse-dev": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive",
        "DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
      }
    }
  }
}

Each profile maps to one tenant/account sign-in; agents pass the target dataverse_url on each tool call. Omit DATAVERSE_TOKEN_CACHE_PROFILE (or leave it empty) for a single-tenant setup — the original shared cache filenames are used.

Safety Guards

Most write and delete tools are not registered by default, so they do not appear to the agent until explicitly enabled. One exception is dataverse_execute_batch, which is always visible but only allows GET requests unless DATAVERSE_ALLOW_WRITE=true. This prevents accidental mutations when you only need to read or inspect data while still allowing safe batch reads by default.

{
  "servers": {
    "dataverse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive",
        "DATAVERSE_ALLOW_WRITE": "true",
        "DATAVERSE_ALLOW_DELETE": "true"
      }
    }
  }
}

Each flag is independent — set only DATAVERSE_ALLOW_WRITE=true to allow creates and updates while keeping deletes disabled.

Reliability and Limits

These behaviors are built in and need no configuration:

• Automatic retries — requests throttled by Dataverse service-protection limits or hitting transient gateway errors are retried automatically; read-only requests are also retried on timeouts and connection failures.
• Response size cap — responses larger than 5 MB are replaced with an error asking the agent to narrow the query with select, top, or filter.
• Consistent errors — every tool returns JSON; failures have the shape {"error": true, "message": "..."} with the Dataverse error code included and the message capped in length.
• Server-side paging — list tools request right-sized pages from Dataverse instead of full 5,000-record pages.

Client Setup

Claude

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dataverse-mcp": {
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

Claude Code

Add via the CLI:

claude mcp add dataverse-mcp --env DATAVERSE_AUTH_TYPE=interactive uvx dataverse-mcp

Or add directly to .claude/settings.json (project) or ~/.claude/settings.json (user):

{
  "mcpServers": {
    "dataverse-mcp": {
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

Run from a local checkout

{
  "mcpServers": {
    "dataverse-mcp-local": {
      "command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "dataverse_mcp.server"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

GitHub Copilot

Add to .vscode/mcp.json in your project root.

Run from PyPI

{
  "servers": {
    "dataverse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dataverse-mcp"],
      "env": {
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

Run from a local checkout

{
  "servers": {
    "dataverse-mcp-local": {
      "type": "stdio",
      "command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "dataverse_mcp.server"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
        "DATAVERSE_AUTH_TYPE": "interactive"
      }
    }
  }
}

Multi-environment targeting

A single server instance can target any Dataverse org — pass dataverse_url on each tool call:

{
  "dataverse_url": "https://yourorg.crm.dynamics.com",
  "entity_set_name": "accounts",
  "select": ["name", "accountid"],
  "top": 10
}

dataverse_url is required on every tool call. Use dataverse_list_environments to discover available environments if you do not yet know the URL.

Tools

184 tools grouped by domain below. Every tool returns JSON and requires dataverse_url on each call.

The Gate column shows when a tool is registered:

dataverse_execute_batch is default but rejects non-GET operations unless DATAVERSE_ALLOW_WRITE=true.

Tool categories

Use DATAVERSE_TOOLS to register only the tool categories your agent needs. This shrinks the visible tool list and reduces token overhead.

core is always registered even when not listed. When DATAVERSE_TOOLS is unset or empty, all categories register (current default behaviour). Category gating composes with DATAVERSE_ALLOW_WRITE and DATAVERSE_ALLOW_DELETE: a tool registers only when its category is enabled AND its write/delete flag (if any) is set.

Environment & identity

Security administration

Async jobs

Web resources

Records & data

Tables & columns

Relationships

Choices (option sets)

Alternate keys

Solutions & publishers

Filesystem I/O note. dataverse_export_solution can write the decoded .zip to a local path when output_path is supplied. dataverse_import_solution can read a local .zip when input_path is supplied. Both paths are resolved on the machine running the MCP server. Use output_path / input_path for solutions larger than ~3 MB (the inline base64 threshold).

Cloud flows & processes

Forms

Views

Model-driven apps

Connection references

Environment variables — definitions

Environment variables — values

Plug-in registration

Plug-in tracing & statistics

Custom APIs

Development

# Install dependencies
uv sync

# Run the MCP inspector (interactive testing)
uv run mcp dev src/dataverse_mcp/server.py

# Run the server directly
uv run python -m dataverse_mcp.server

# Compile check
uv run python -m py_compile src/dataverse_mcp/server.py

Restart the MCP server in VS Code after code changes to pick up the new source.

License

MIT