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!

$3

Add to your claude_desktop_config.json:

``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"
]
}
}
}
`

$3

Add to your .vscode/mcp.json:

`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"
]
}
}
}
`

$3

Add to your Cline MCP configuration:

`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"
]
}
}
}
`

> 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

$3

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"

$3

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:

`bash


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

$3

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.

$3

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

#### Option 1: CLI Arguments

Pass credentials directly through the MCP configuration:

`json
{
"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:
`bash
cp .env.example .env
`

2. Fill in your Dataverse credentials in .env:
`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:
`json
{
"servers": {
"dataverse": {
"type": "stdio",
"command": "node",
"args": ["./build/src/index.js"]
}
}
}
`

$3

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

$3

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:
`json
{
"table": "contacts",
"data": {
"firstname": "John",
"lastname": "Doe",
"emailaddress1": "john.doe@example.com"
}
}
`

$3

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:
`json
{
"table": "contacts",
"id": "12345678-1234-1234-1234-123456789012",
"select": "firstname,lastname,emailaddress1"
}
`

$3

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:
`json
{
"table": "accounts",
"select": "name,revenue,industrycode",
"filter": "revenue gt 1000000",
"orderby": "name asc",
"top": 10
}
`

$3

Update an existing record.

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

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

$3

Delete a record.

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

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

$3

List all available tables in the environment.

Parameters: None

Usage Examples

$3

`
Create a new contact with name "Jane Smith" and email "jane.smith@example.com"
`

$3

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

$3

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

$3

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

OData Query Examples

$3

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

$3

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

$3

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

Troubleshooting

$3

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

$3

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

`env
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

$3


`bash
npm run build
`

$3

`bash
npm run watch
`

$3

`bash
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:

$3

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

`bash


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

$3

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

`bash
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