npm package: @microsoft/dataversecli
Description: CLI tool for Dataverse, including stdio MCP server
Latest version: 0.0.31

# Dataverse CLI

A command-line tool for Microsoft Dataverse that provides multiple capabilities for working with Dataverse environments.

## Installation

### Global Installation

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

### Use with npx (No Installation Required)

```bash
npx @microsoft/dataversecli <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.

## Available Commands

### `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
dataversecli 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
dataversecli 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
dataversecli mcp https://myorg.crm.dynamics.com
```

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

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

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

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

## 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/dataversecli 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/dataversecli", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}
```

**With logging enabled for troubleshooting:**
```json
{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "@microsoft/dataversecli",
        "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/dataversecli",
        "mcp",
        "https://yourorg.crm.dynamics.com",
        "--preview"
      ],
      "type": "stdio"
    }
  }
}
```

## Authentication

The MCP server uses Microsoft Authentication Library (MSAL) with device code flow for authentication. When you start the server:

1. A browser window will open automatically
2. Sign in with your Microsoft account that has access to the Dataverse environment
3. The server will cache your authentication token for future use

## Supported Platforms

- **Windows** (x64)
- **macOS** (ARM64 - Apple Silicon)

## Troubleshooting

### Enable Logging

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

```bash
dataversecli 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"**
- This package currently supports Windows (x64) and macOS (ARM64/Apple Silicon)
- For other platforms, please use the .NET version directly

**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
# General help
dataversecli --help

# MCP command help
dataversecli mcp --help
```

## Support 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/DataverseMcpCLI)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)