README.md
Explore metadata, query data, and perform operations in D365 environments.
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= |
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:
- Check prerequisites (Node.js 18+, dependencies)
- Guide you through D365 environment configuration
- Test connectivity to your D365 environments
- Generate configuration files
- 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",
"clientSec
Tools (5)
list_environmentsList all configured D365 environments with connection statusexecute_odataExecute raw OData paths for queries, single records, or countsaggregatePerform aggregations like SUM, AVG, COUNT, or percentiles on entity datacreate_recordCreate new records in non-production environmentscompare_schemasCompare entity schemas between two environments to detect schema driftEnvironment Variables
tenantIdrequiredAzure AD Tenant IDclientIdrequiredAzure AD Client IDclientSecretrequiredAzure AD Client SecretConfiguration
claude_desktop_config.json
{"mcpServers": {"d365fo": {"command": "npx", "args": ["-y", "@zhound/d365fo-mcp-server"]}}}Try it
→List all my configured D365 environments and check their connection status.
→Show me the schema for the SalesOrderHeader entity in the UAT environment.
→Calculate the average invoice amount for the last quarter using the aggregate tool.
→Compare the schema of the Customer entity between my Dev and UAT environments to find differences.
→Create a new test record in the non-production environment for the Vendor entity.