npm package: @microsoft/dataverse
Description: CLI tool for Dataverse, including stdio MCP server. Preview.
Latest version: 1.0.15

# Dataverse CLI (Preview)

A command-line tool for Microsoft Dataverse that provides authentication management, environment operations, and an MCP (Model Context Protocol) server for AI assistant integration.

## Installation

### Global Installation

```bash
npm install -g @microsoft/dataverse
```

### Use with npx (No Installation Required)

```bash
npx @microsoft/dataverse <command> [options]
```

## Prerequisites

Before you can use the Dataverse MCP server, the following setup steps must be completed by your administrators:

### 1. Azure Tenant Admin: Grant Admin Consent

An Azure tenant administrator must grant admin consent for the Dataverse MCP CLI tool application.

**Steps:**
1. Navigate to: `https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457`
   - Replace `{your-tenant-id}` with your actual Azure tenant ID
2. Sign in as an Azure tenant administrator
3. Review and grant the requested permissions

### 2. Dataverse Admin: Enable MCP Server

A Dataverse organization administrator must enable the MCP server feature for your environment.

**Resources:**
- [Enable Dataverse MCP (Production)](https://aka.ms/enableDataverseMcp)
- [Enable Dataverse MCP (Preview)](https://aka.ms/enableDataverseMcpPreview)

### 3. Dataverse Admin: Allow the MCP CLI Tool

A Dataverse organization administrator must add the Dataverse MCP CLI tool to the allowed client applications list.

**Steps:**
1. Follow the instructions at: [Configure MCP Client List](https://aka.ms/configuremcpclientlist)
2. Add the application with App ID: `0c412cc3-0dd6-449b-987f-05b053db9457`
   - This will appear as "Dataverse MCP CLI tool" in the UI

> **Note:** All three prerequisite steps must be completed before you can successfully authenticate and connect to your Dataverse environment.

## Automatic Update Checking

The CLI automatically checks for new versions on npmjs.com when you run any command. If a newer version is available, you'll see a notification prompting you to update.

## Available Commands

### `install` - Install a Specific Version

Install a specific version of the Dataverse CLI, or update to the latest version.

#### Usage

**Install latest version:**
```bash
dataverse install latest
```

**Install specific version:**
```bash
dataverse install 0.0.2
```

**With npx:**
```bash
npx @microsoft/dataverse install latest
npx @microsoft/dataverse install 0.0.2
```

This command works whether you have a global installation or are using npx. It will automatically detect your installation method and install accordingly.

### `auth` - Authentication Profile Management

Manage authentication profiles for connecting to Dataverse environments.

#### `auth create` - Create a New Profile

```bash
# Interactive authentication (opens browser or system dialog)
dataverse auth create --environment https://myorg.crm.dynamics.com

# Named profile
dataverse auth create --environment https://myorg.crm.dynamics.com --name prod

# Device code flow (for environments without a browser)
dataverse auth create --environment https://myorg.crm.dynamics.com --deviceCode

# Service principal with client secret
dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId>

# Custom Entra app client ID (use your own app registration instead of the default)
dataverse auth create --environment https://myorg.crm.dynamics.com --clientid <your-app-guid>
```

Run `dataverse auth create --help` for all options including certificate auth, managed identity, and federated auth.

#### `auth select` - Switch Active Profile

```bash
# Interactive picker (arrow keys, type to filter)
dataverse auth select

# By index or name
dataverse auth select --index 1
dataverse auth select --name prod
```

#### `auth list` - List All Profiles

```bash
dataverse auth list
dataverse auth list --json
```

#### `auth who` - Show Current Profile

```bash
dataverse auth who
dataverse auth who --json
```

#### `auth remove` - Remove a Profile

```bash
# Remove by 1-based index (from 'auth list')
dataverse auth remove --index 1

# Remove by name
dataverse auth remove --name prod

# Remove all profiles
dataverse auth remove --all
```

### `org` (or `env`) - Environment Operations

Query Dataverse environments using the current authentication profile.

#### `org who` - Current Organization Info

```bash
dataverse org who
dataverse org who --environment https://myorg.crm.dynamics.com
dataverse org who --json
```

#### `org list` - List Accessible Environments

```bash
dataverse org list
dataverse org list --filter contoso
dataverse org list --json
```

### `mcp` - MCP Server for Dataverse

Starts an MCP (Model Context Protocol) server that connects to your Dataverse environment, enabling AI assistants like Claude to interact with your Dataverse data.

#### Usage

```bash
dataverse mcp <orgUrl> [options]
```

**Arguments:**
- `<orgUrl>` - Your Dataverse organization URL (e.g., `https://myorg.crm.dynamics.com`)

**Options:**
- `--validate` - Validate MCP endpoints and authentication setup without starting the server
- `--log-level <level>` - Set logging level: Trace, Debug, Information, Warning, Error, Critical (default: Warning)
- `--log-file` - Enable logging to a file in the temp directory
- `--preview` - Use preview MCP endpoint (`api/mcp_preview` instead of `api/mcp`)

#### Examples

**Validate setup (recommended first step):**
```bash
dataverse mcp https://myorg.crm.dynamics.com --validate
```

This will test both the GA and Preview endpoints and verify that:
- Authentication is working correctly
- The MCP server is enabled
- The MCP CLI tool is in the allowed applications list

If validation fails, the output will provide specific guidance on which prerequisite steps need to be completed.

**Basic usage with stdio transport:**
```bash
dataverse mcp https://myorg.crm.dynamics.com
```

**With npx:**
```bash
npx @microsoft/dataverse mcp https://myorg.crm.dynamics.com
```

**Use preview endpoint:**
```bash
dataverse mcp https://myorg.crm.dynamics.com --preview
```

**Enable debug logging:**
```bash
dataverse mcp https://myorg.crm.dynamics.com --log-level Debug
```

**Enable file logging (useful for troubleshooting):**
```bash
dataverse mcp https://myorg.crm.dynamics.com --log-file
```

### `mcp allow` - Allow an MCP Client Application

Ensures an Azure AD application is in the Dataverse MCP allowed clients list for the current profile's environment. This is an alternative to the manual admin step in Prerequisites.

```bash
dataverse mcp allow 0c412cc3-0dd6-449b-987f-05b053db9457
```

> **Note:** Requires the authenticated user to have Dataverse admin permissions on the target environment.

## Using with Claude Desktop

To use the Dataverse MCP server with Claude Desktop, add it to your MCP configuration.

### Quick Setup

```bash
claude mcp add dataverse -t stdio -- npx -y @microsoft/dataverse mcp https://yourorg.crm.dynamics.com
```

### Manual Configuration

Edit your Claude Desktop MCP configuration file:

**Location:**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration:**
```json
{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@microsoft/dataverse", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}
```

**With logging enabled for troubleshooting:**
```json
{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "@microsoft/dataverse",
        "mcp",
        "https://yourorg.crm.dynamics.com",
        "--log-level", "Debug",
        "--log-file"
      ],
      "type": "stdio"
    }
  }
}
```

**Using the preview endpoint:**
```json
{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "@microsoft/dataverse",
        "mcp",
        "https://yourorg.crm.dynamics.com",
        "--preview"
      ],
      "type": "stdio"
    }
  }
}
```

## Authentication

The CLI uses Microsoft Authentication Library (MSAL) for authentication. Profiles and tokens are cached locally.

**First-time setup:**
```bash
dataverse auth create --environment https://myorg.crm.dynamics.com
```

This opens a browser or system authentication dialog. After signing in, the profile is saved and subsequent commands (including `mcp`) use cached tokens without re-prompting.

**Multiple environments:**
```bash
dataverse auth create --environment https://dev.crm.dynamics.com --name dev
dataverse auth create --environment https://prod.crm.dynamics.com --name prod
dataverse auth select --name dev
```

**Service principal (CI/CD):**
```bash
dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId> --environment https://myorg.crm.dynamics.com
```

## Supported Platforms

- **Windows** (x64, ARM64)
- **macOS** (x64, ARM64 / Apple Silicon)
- **Linux** (x64, ARM64)

## Troubleshooting

### Enable Logging

If you encounter issues, enable file logging to capture detailed diagnostic information:

```bash
dataverse mcp https://yourorg.crm.dynamics.com --log-level Debug --log-file
```

Log files are written to your system's temporary directory. The exact location will be displayed when logging starts.

### Common Issues

**"No compatible binary found for your platform"**
- Supported: Windows (x64, ARM64), macOS (x64, ARM64), Linux (x64, ARM64)
- For other platforms, please build from source with `dotnet publish`

**Authentication failures**
- Ensure you have access to the Dataverse environment
- Check that your organization URL is correct
- Try clearing your token cache and re-authenticating

**MCP connection issues in Claude Desktop**
- Verify the configuration JSON syntax is correct
- Check that the organization URL is accessible
- Enable `--log-file` to capture detailed error messages
- Restart Claude Desktop after configuration changes

## Getting Help

```bash
dataverse --help
dataverse auth --help
dataverse auth create --help
dataverse org --help
dataverse mcp --help
dataverse mcp allow --help
```

## Supported MCP Operations

The MCP server supports the following operations:

- **Tools**: List and call Dataverse tools
- **Prompts**: List and retrieve prompts
- **Resources**: List and read Dataverse resources

## License

MIT

## Links

- [GitHub Repository](https://dev.azure.com/dynamicscrm/OneCRM/_git/DataverseCLI)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)