Dataverse MCP Server

A Model Context Protocol (MCP) server that provides comprehensive CRUD operations for Microsoft Dataverse. This server enables seamless integration with Dataverse environments, allowing you to create, read, update, delete, and query records using natural language through MCP-compatible clients like Claude.

Quick Start with NPX

The easiest way to use the Dataverse MCP server is with npx - no installation required!

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "dataverse-mcp",
        "--clientId", "your-client-id",
        "--clientSecret", "your-client-secret", 
        "--tenantId", "your-tenant-id",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

For Cursor

Add to your .vscode/mcp.json:

{
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "dataverse-mcp",
        "--clientId", "your-client-id",
        "--clientSecret", "your-client-secret",
        "--tenantId", "your-tenant-id", 
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

For Cline

Add to your Cline MCP configuration:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "dataverse-mcp",
        "--clientId", "your-client-id",
        "--clientSecret", "your-client-secret",
        "--tenantId", "your-tenant-id",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

Note: The first time you use npx dataverse-mcp, it will automatically download and install the package. Subsequent runs will use the cached version.

Features

• ✅ Complete CRUD Operations: Create, read, update, and delete records
• ✅ Advanced Querying: Support for OData filters, sorting, pagination, and expansion
• ✅ Table Discovery: List available tables and their metadata
• ✅ Robust Authentication: OAuth 2.0 client credentials flow with automatic token refresh
• ✅ Comprehensive Logging: Detailed logging for debugging and monitoring
• ✅ Input Validation: Thorough validation of all inputs and OData queries
• ✅ Error Handling: Graceful error handling with detailed error messages
• ✅ Flexible Configuration: Support for both environment variables and MCP configuration arguments
• ✅ NPX Ready: Run directly with npx - no installation required

Prerequisites

Before using this MCP server, you need:

1. Microsoft Dataverse Environment: Access to a Dataverse environment
2. Azure AD App Registration: An app registration with appropriate permissions
3. Node.js: Version 18 or higher (for npx usage)

Setup

1. Azure AD App Registration

1. Go to Azure Portal → Microsoft Entra ID → Manage → App Registrations
2. Click "New registration"
3. Name your application (e.g., "Dataverse MCP Server")
4. Leave Redirect URI blank
5. Click "Register"
6. Note down the Application (client) ID and Directory (tenant) ID
7. Go to "Client credentials" → "Add a certificate or secret" → "New client secret"
8. Add a description "Dataverse MCP Server" and an Expiration date.
9. Create a secret and note down the Client Secret and Value
10. Go to "API permissions" → "Add a permission" → "Dynamics CRM"
11. Add "user_impersonation" permission (Application permission)
12. Click "Add permissions"

2. Installation

Recommended: NPX (No installation required)

The easiest way is to use npx as shown in the Quick Start section above. This automatically handles installation, updates, and execution.

Alternative: Manual Installation

If you prefer to clone and build locally for development or customization:

# Clone the repository
git clone https://github.com/yourusername/dataverse-mcp.git
cd dataverse-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

NPX Usage (Recommended)

Use npx dataverse-mcp with your MCP client as shown in the Quick Start section. This is the easiest method and requires no local installation.

Manual Installation Configuration

If you've installed manually, you can configure the server in several ways:

Option 1: CLI Arguments

Pass credentials directly through the MCP configuration:

{
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "node",
      "args": [
        "./build/src/index.js",
        "--clientId", "your-client-id",
        "--clientSecret", "your-client-secret",
        "--tenantId", "your-tenant-id",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

Option 2: Environment Variables

1. Copy .env.example to .env:

   cp .env.example .env

2. Fill in your Dataverse credentials in .env:

   # Dataverse Authentication (Required)
   DATAVERSE_CLIENT_ID=your-client-id-here
   DATAVERSE_CLIENT_SECRET=your-client-secret-here
   DATAVERSE_TENANT_ID=your-tenant-id-here
   DATAVERSE_ENVIRONMENT_URL=https://yourorg.crm.dynamics.com
   
   # Optional Configuration
   LOG_LEVEL=info
   RATE_LIMIT_REQUESTS_PER_MINUTE=60

3. Use in MCP configuration:

   {
     "servers": {
       "dataverse": {
         "type": "stdio",
         "command": "node",
         "args": ["./build/src/index.js"]
       }
     }
   }

Configuration Parameters

When using CLI arguments (both npx and manual), you can pass:

• --clientId: Azure AD Application (client) ID
• --clientSecret: Azure AD Client Secret
• --tenantId: Azure AD Directory (tenant) ID
• --environmentUrl: Dataverse environment URL (e.g., https://yourorg.crm.dynamics.com)
• --logLevel: Log level (error, warn, info, debug) - defaults to 'info'
• --rateLimit: Rate limit requests per minute - defaults to 60

Note: CLI arguments take precedence over environment variables.

Available Tools

1. dataverse_create_record

Create a new record in a Dataverse table.

Parameters:

• table (string, required): Table name (e.g., "contacts", "accounts")
• data (object, required): Record data as key-value pairs

Example:

{
  "table": "contacts",
  "data": {
    "firstname": "John",
    "lastname": "Doe",
    "emailaddress1": "[email protected]"
  }
}

2. dataverse_read_record

Read a single record by ID.

Parameters:

• table (string, required): Table name
• id (string, required): Record GUID
• select (string, optional): Comma-separated columns to select
• expand (string, optional): Related entities to expand

Example:

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012",
  "select": "firstname,lastname,emailaddress1"
}

3. dataverse_query_records

Query multiple records with OData filters.

Parameters:

• table (string, required): Table name
• select (string, optional): Columns to select
• filter (string, optional): OData filter expression
• orderby (string, optional): OData orderby expression
• top (number, optional): Maximum records to return
• skip (number, optional): Records to skip (pagination)
• expand (string, optional): Related entities to expand
• count (boolean, optional): Include total count

Example:

{
  "table": "accounts",
  "select": "name,revenue,industrycode",
  "filter": "revenue gt 1000000",
  "orderby": "name asc",
  "top": 10
}

4. dataverse_update_record

Update an existing record.

Parameters:

• table (string, required): Table name
• id (string, required): Record GUID
• data (object, required): Data to update

Example:

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012",
  "data": {
    "jobtitle": "Senior Developer",
    "telephone1": "555-0123"
  }
}

5. dataverse_delete_record

Delete a record.

Parameters:

• table (string, required): Table name
• id (string, required): Record GUID

Example:

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012"
}

6. dataverse_list_tables

List all available tables in the environment.

Parameters: None

Usage Examples

Creating a Contact

Create a new contact with name "Jane Smith" and email "[email protected]"

Querying Accounts

Find all accounts with revenue greater than $1 million, ordered by name

Reading a Specific Record

Get the contact with ID 12345678-1234-1234-1234-123456789012, including their full name and email

Updating a Record

Update the job title of contact 12345678-1234-1234-1234-123456789012 to "Senior Manager"

OData Query Examples

Filtering

• firstname eq 'John' - Exact match
• revenue gt 1000000 - Greater than
• createdon ge 2024-01-01T00:00:00Z - Date comparison
• contains(name, 'Microsoft') - Contains text

Ordering

• name asc - Ascending order
• createdon desc - Descending order
• revenue desc, name asc - Multiple fields

Selecting Fields

• firstname,lastname,emailaddress1 - Specific fields
• * - All fields (not recommended for performance)

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your client ID, secret, and tenant ID
   • Ensure admin consent was granted for API permissions
   • Check that the client secret hasn't expired

2. Environment URL Invalid

   • Ensure the URL format is correct: https://yourorg.crm.dynamics.com
   • Verify you have access to the Dataverse environment

3. Table Not Found

   • Use dataverse_list_tables to see available tables
   • Check table name spelling (case-sensitive)

4. Permission Denied

   • Verify your app registration has the correct permissions
   • Ensure the user/app has access to the specific table

Logging

Set --logLevel=debug in your MCP configuration for detailed logging, or use environment variables:

LOG_LEVEL=debug

Security Considerations

• Never commit your .env file - It contains sensitive credentials
• Use least privilege - Only grant necessary permissions to your app registration
• Rotate secrets regularly - Update client secrets periodically
• Monitor usage - Keep track of API calls and unusual activity

Development

Building

npm run build

Watching for Changes

npm run watch

Testing with MCP Inspector

npm run inspector

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the Microsoft Dataverse documentation
3. Open an issue in this repository

Authentication

The Dataverse MCP server supports two authentication methods:

1. Personal Authentication (Recommended)

Uses your personal Microsoft account with Device Code Flow. No complex Azure AD setup required!

# For npx users - pre-authenticate once (recommended)
npx dataverse-mcp --auth --clientId "your-client-id" --tenantId "your-tenant-id" --environmentUrl "https://yourorg.crm.dynamics.com"

# Then use normally in your MCP client
npx dataverse-mcp --clientId "your-client-id" --tenantId "your-tenant-id" --environmentUrl "https://yourorg.crm.dynamics.com"

What happens during authentication:

1. You'll see a device code and URL in the console
2. Visit the URL in your browser and enter the code
3. Sign in with your Microsoft account (complete MFA if required)
4. Grant permission to access Dataverse
5. Token is cached for future use

2. Application Credentials (Advanced)

Uses Azure AD app registration with client secret for unattended scenarios.

npx dataverse-mcp --clientId "your-client-id" --clientSecret "your-client-secret" --tenantId "your-tenant-id" --environmentUrl "https://yourorg.crm.dynamics.com"

Requires:

• Azure AD app registration with Dataverse API permissions
• Application user setup in Dataverse environment