D365 Finance & Operations MCP Server

An MCP (Model Context Protocol) server that provides access to Microsoft Dynamics 365 Finance & Operations environments. Enables AI assistants like Claude to explore D365 metadata, query data, and perform write operations on non-production environments.

Features

• Multi-Environment Support - Connect to multiple D365 environments (production, UAT, dev)
• Read/Write Operations - Query data on all environments; create, update, delete on non-production only
• Production Safety - Production environments are always read-only by design
• MCP Resources for schema discovery and metadata exploration
• 22 Specialized Tools for flexible data access, aggregation, batch operations, and analysis
• Environment Dashboard - Health monitoring, API statistics, and operation tracking
• Secure Authentication via Azure AD client credentials
• Automatic Metadata Caching (24-hour TTL, per-environment)

Architecture

Resources

| Resource | URI | Purpose | |----------|-----|---------| | Entities List | d365://entities?filter=<pattern> | List all entities with optional wildcard filtering | | Entity Schema | d365://entity/{entityName} | Full schema for any entity (fields, keys, navigation properties) | | Navigation Properties | d365://navigation/{entityName} | Entity relationships and navigation properties | | Enum Definitions | d365://enums | All enum types with their values | | Saved Queries | d365://queries | List saved query templates | | Dashboard | d365://dashboard | JSON metrics for all environments (health, API stats, recent operations) |

Tools

All tools support an optional environment parameter to target specific D365 environments.

| Tool | Purpose | |------|---------| | list_environments | List all configured D365 environments with connection status | | set_environment | Set the working environment for the current session | | describe_entity | Quick schema lookup for an entity | | execute_odata | Execute raw OData paths (queries, single records, counts) | | aggregate | Perform aggregations (SUM, AVG, COUNT, MIN, MAX, COUNTDISTINCT, percentiles) on entity data | | get_related | Follow entity relationships to retrieve related records | | export | Export query results to CSV, JSON, or TSV format | | compare_periods | YoY, QoQ, MoM period comparisons with change calculations | | trending | Time series analysis with growth rates and moving averages | | save_query | Save reusable query templates with parameter support | | execute_saved_query | Execute saved query templates with parameter substitution | | delete_saved_query | Delete saved query templates | | join_entities | Cross-entity joins using $expand or client-side join | | batch_query | Execute multiple queries in parallel | | search_entity | Robust entity search with automatic fallback strategies | | analyze_customer | Comprehensive single-call customer analysis | | create_record | Create new records (non-production environments only) | | update_record | Update existing records (non-production environments only) | | delete_record | Delete records (non-production environments only) | | batch_crud | Execute multiple create/update/delete operations in a single batch request (non-production only) | | compare_schemas | Compare entity schemas between two environments to detect schema drift | | dashboard | Display environment dashboard with health status, API statistics, and recent operations |

Installation

From npm (Recommended)

npx @zhound/d365fo-mcp-server

Or install globally:

npm install -g @zhound/d365fo-mcp-server
d365fo-mcp

From Source

git clone https://github.com/zhound420/D365FO-claude-connector.git
cd D365FO-claude-connector
npm install
npm run build

Quick Start (Recommended)

Run the interactive setup wizard:

npm run setup

The wizard will:

1. Check prerequisites (Node.js 18+, dependencies)
2. Guide you through D365 environment configuration
3. Test connectivity to your D365 environments
4. Generate configuration files
5. Configure Claude Desktop and/or Claude Code

After setup, restart Claude Desktop (Cmd+Q then reopen on macOS, or Ctrl+Q on Windows) or start a new Claude Code session.

Configuration

Multi-Environment Configuration (Recommended)

Create a d365-environments.json file in the project root or working directory:

{
  "environments": [
    {
      "name": "production",
      "displayName": "Production",
      "type": "production",
      "tenantId": "your-tenant-id",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "environmentUrl": "https://your-company.operations.dynamics.com",
      "default": true
    },
    {
      "name": "uat",
      "displayName": "UAT (Tier 2)",
      "type": "non-production",
      "tenantId": "your-tenant-id",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "environmentUrl": "https://your-company-uat.sandbox.operations.dynamics.com"
    },
    {
      "name": "dev",
      "displayName": "Dev Sandbox",
      "type": "non-production",
      "tenantId": "your-tenant-id",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "environmentUrl": "https://your-company-dev.sandbox.operations.dynamics.com"
    }
  ]
}

Environment Types:

• type: "production" - Read-only access (all write operations are blocked)
• type: "non-production" - Full read/write access (create, update, delete enabled)

Copy d365-environments.example.json as a starting point.

Single Environment (Legacy)

The server also supports the following environment variables (fallback if no JSON config):

| Variable | Description | |----------|-------------| | D365_TENANT_ID | Azure AD tenant ID | | D365_CLIENT_ID | Azure AD application (client) ID | | D365_CLIENT_SECRET | Azure AD client secret | | D365_ENVIRONMENT_URL | D365 F&O environment URL (e.g., https://contoso.operations.dynamics.com) | | D365_ENVIRONMENT_TYPE | Optional: "production" or "non-production" (defaults to "production" for safety) |

Optional: | Variable | Default | Description | |----------|---------|-------------| | D365_TRANSPORT | stdio | Transport mode (stdio or http) | | D365_HTTP_PORT | 3000 | HTTP port (when using http transport) | | D365_LOG_LEVEL | info | Logging level | | D365_PAGINATION_TIMEOUT_MS | 60000 | Timeout (ms) for paginated requests on large datasets | | D365_CONFIG_FILE | | Path to config file if not in default location |

Azure AD App Registration

Step 1: Create Azure AD App

1. Go to Azure Portal > Azure Active Directory > App registrations
2. Click "New registration"
3. Name it (e.g., "D365 MCP Server")
4. Select "Accounts in this organizational directory only"
5. Click Register

Step 2: Configure API Permissions

1. Go to "API permissions" > "Add a permission"
2. Select "Dynamics 365 Finance and Operations"
3. Choose "Application permissions" > CustomService.ReadWrite.All
4. Click "Grant admin consent for [your organization]"

Step 3: Create Client Secret

1. Go to "Certificates & secrets" > "New client secret"
2. Add a description and expiry period
3. Copy the secret value immediately (shown only once)
4. Note down:
   • Tenant ID: Found on the Overview page
   • Client ID: Application (client) ID on Overview page
   • Client Secret: The value you just copied

Step 4: Register App in D365 Environments

Important: This step must be done in each D365 environment (Production, UAT, Dev) you want to connect to.

1. In D365 F&O, navigate to: System Administration > Setup > Azure Active Directory applications

2. Click "New" to add a record: | Field | Value | |-------|-------| | Client ID | The Application (client) ID from Azure AD | | Name | Descriptive name (e.g., "MCP Server Integration") | | User ID | A D365 user account for the app to run as |

3. The User ID determines what data the app can access:

   • Use a service account with appropriate security roles
   • For read-only access: assign roles like "View all data"
   • For write access on non-production: assign roles that allow create/update/delete

4. Repeat for each environment you want to connect to

Note: If you skip this step, API calls will fail with 401 Unauthorized or 403 Forbidden errors even though Azure AD authentication succeeded.

Setup

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Microsoft D365": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_TENANT_ID": "your-tenant-id",
        "D365_CLIENT_ID": "your-client-id",
        "D365_CLIENT_SECRET": "your-client-secret",
        "D365_ENVIRONMENT_URL": "https://your-env.operations.dynamics.com"
      }
    }
  }
}

Claude Code (CLI)

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "Microsoft D365": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_TENANT_ID": "your-tenant-id",
        "D365_CLIENT_ID": "your-client-id",
        "D365_CLIENT_SECRET": "your-client-secret",
        "D365_ENVIRONMENT_URL": "https://your-env.operations.dynamics.com"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop or Claude Code.

Environment Visibility Configuration

When using multiple D365 environments, you can configure how they appear in Claude:

Option A: Separate Servers per Environment (Recommended)

This option shows each environment as a separate MCP server in Claude's sidebar:

{
  "mcpServers": {
    "D365-production": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_CONFIG_FILE": "/path/to/d365fo-mcp-server/d365-environments.json",
        "D365_SINGLE_ENV": "production"
      }
    },
    "D365-uat": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_CONFIG_FILE": "/path/to/d365fo-mcp-server/d365-environments.json",
        "D365_SINGLE_ENV": "uat"
      }
    },
    "D365-dev": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_CONFIG_FILE": "/path/to/d365fo-mcp-server/d365-environments.json",
        "D365_SINGLE_ENV": "dev"
      }
    }
  }
}

Pros:

• Environment is immediately visible in Claude's sidebar
• No ambiguity about which environment a query targets
• Works reliably across all platforms

How it works: The D365_SINGLE_ENV environment variable tells the server to load only that specific environment from d365-environments.json. The D365_CONFIG_FILE ensures the config is found regardless of working directory.

Option B: Single Multi-Environment Server

Use a single server with an environment parameter on each query:

{
  "mcpServers": {
    "d365": {
      "command": "node",
      "args": ["/path/to/d365fo-mcp-server/dist/index.js"],
      "env": {
        "D365_CONFIG_FILE": "/path/to/d365fo-mcp-server/d365-environments.json"
      }
    }
  }
}

Then specify the environment in queries:

{ "entity": "CustomersV3", "top": 10, "environment": "uat" }

Pros:

• Single server process
• Flexibility to query any environment in one session

The interactive setup script (node setup.js) can generate either configuration for you.

Talking to Claude - Example Prompts

Once configured, you can ask Claude natural language questions about your D365 environment. Here are examples organized by capability:

Discov