io.github.zhound420/d365fo-connector

Install

Config snippet generator goes here (5 client tabs)

README

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

```bash
npx @zhound/d365fo-mcp-server
```

Or install globally:

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

### From Source

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

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

```json
{
  "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",
      "clientSec