andrew-dataverse-mcp/README.md

A Model Context Protocol server for Microsoft Dataverse with comprehensive CRUD operations

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

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

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

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

### 1. Azure AD App Registration

1. Go to [Azure Portal](https://portal.azure.com) → 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:

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

### 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:

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

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

### 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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 "jane.smith@example.com"
```

### 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:

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

### Building
```bash
npm run build
```

### Watching for Changes
```bash
npm run watch
```

### Testing with MCP Inspector
```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](https://docs.microsoft.com/en-us/powerapps/developer/data-platform/)
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!**

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

### 2. Application Credentials (Advanced)

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