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

Tools

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

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

Optional:

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: