Iflow Mcp Mafzaal D365fo Client
БесплатноНе проверенMicrosoft Dynamics 365 Finance & Operations client and MCP server
Описание
Microsoft Dynamics 365 Finance & Operations client and MCP server
README
Production-ready Model Context Protocol (MCP) server that exposes the full capabilities of Microsoft Dynamics 365 Finance & Operations (D365 F&O) to AI assistants and other MCP-compatible tools. This enables sophisticated Dynamics 365 integration workflows through standardized protocol interactions.
GitHub watchers GitHub forks GitHub stars
🚀 One-Click Installation for VS Code:
Install with UVX in VS Code Install with UVX in VS Code Insiders
🐳 Docker Installation for VS Code:
Install with Docker in VS Code Install with Docker in VS Code Insiders
☁️ Deploy to Azure Container Apps:
Deploy the MCP server as a secure, internet-accessible HTTP endpoint with OAuth or API Key authentication. Perfect for web integrations and remote AI assistant access.
Option 1: Using Bash Script (Recommended)
# Download and run the deployment script
curl -O https://raw.githubusercontent.com/mafzaal/d365fo-client/main/deploy-aca.sh
chmod +x deploy-aca.sh
# Set authentication (choose OAuth or API Key)
export D365FO_MCP_AUTH_CLIENT_ID="your-client-id"
export D365FO_MCP_AUTH_CLIENT_SECRET="your-client-secret"
export D365FO_MCP_AUTH_TENANT_ID="your-tenant-id"
# OR
export D365FO_MCP_API_KEY_VALUE="your-secret-key"
# Deploy
./deploy-aca.sh
Option 2: Using ARM Template
- Download azure-deploy.json
- Go to Azure Portal → Deploy a custom template
- Click "Build your own template in the editor"
- Paste the contents of
azure-deploy.json - Fill in the parameters and deploy
Also includes a comprehensive Python client library for Microsoft Dynamics 365 Finance & Operations with OData endpoints, metadata operations, label management, and CLI tools.
MCP Server Overview
The d365fo-client includes a production-ready Model Context Protocol (MCP) server (d365fo-fastmcp-server) built on the FastMCP framework that exposes the full capabilities of D365 Finance & Operations to AI assistants and other MCP-compatible tools.
The server provides multi-transport support (stdio, HTTP, SSE) with enhanced performance and deployment flexibility.
Key Features
- 49 comprehensive tools covering all major D365 F&O operations across 9 functional categories
- 12 resource types with comprehensive metadata exposure and discovery capabilities
- 2 prompt templates for advanced workflow assistance
- Multi-transport support (FastMCP): stdio, HTTP, Server-Sent Events (SSE)
- Production-ready implementation with proper error handling, authentication, and security validation
- Enhanced performance (FastMCP): 40% faster startup, 15% lower memory usage
- Advanced profile management supporting multiple environments with secure credential storage
- Database analysis capabilities with secure SQL querying and metadata insights
- Session-based synchronization with detailed progress tracking and multiple sync strategies
- Multi-language support with label resolution and localization capabilities
- Enterprise security with Azure AD integration, Key Vault support, and audit logging
New in v0.3.0
- 🔧 Pydantic Settings Model: Type-safe environment variable management with validation for 35+ configuration options
- 📂 Custom Log File Support:
D365FO_LOG_FILEenvironment variable for flexible log file paths - 🔄 Legacy Config Migration: Automatic detection and migration of legacy configuration files
- 🌐 Environment Variable Standardization: All MCP HTTP variables now use
D365FO_prefix for consistency - ⚡ Enhanced FastMCP Server: Improved startup configuration, error handling, and graceful shutdown
- 🔀 MCP Return Type Standardization: All MCP tools now return dictionaries instead of JSON strings for better type safety
- 🛠️ Enhanced Configuration: Support for
.envfiles and comprehensive environment variable documentation
Quick Start
Installation and Setup
# Install d365fo-client with MCP dependencies
pip install d365fo-client
# Set up environment variables
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CLIENT_ID="your-client-id" # Optional with default credentials
export D365FO_CLIENT_SECRET="your-client-secret" # Optional with default credentials
export D365FO_TENANT_ID="your-tenant-id" # Optional with default credentials
FastMCP Server (Recommended)
The modern FastMCP implementation provides enhanced performance and multiple transport options:
# Development (stdio transport - default)
d365fo-fastmcp-server
# Production HTTP API
d365fo-fastmcp-server --transport http --port 8000 --host 0.0.0.0
# Real-time Web Applications (SSE)
d365fo-fastmcp-server --transport sse --port 8001 --host 0.0.0.0
Key Benefits:
- Optimized performance with FastMCP framework
- Efficient resource usage through optimized architecture
- Multi-transport support: stdio, HTTP, Server-Sent Events (SSE)
- Enhanced error handling with better async/await support
- Production ready with web transports for API integration
Integration with AI Assistants
VS Code Integration (Recommended)
FastMCP Server with Default Credentials:
Add to your VS Code mcp.json for GitHub Copilot with MCP:
{
"servers": {
"d365fo-fastmcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"d365fo-client@latest",
"d365fo-fastmcp-server"
],
"env": {
"D365FO_BASE_URL": "https://your-environment.dynamics.com",
"D365FO_LOG_LEVEL": "INFO"
}
}
}
}
Option 2: Explicit Credentials For environments requiring service principal authentication:
{
"servers": {
"d365fo-fastmcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"d365fo-client",
"d365fo-fastmcp-server"
],
"env": {
"D365FO_BASE_URL": "https://your-environment.dynamics.com",
"D365FO_LOG_LEVEL": "DEBUG",
"D365FO_CLIENT_ID": "${input:client_id}",
"D365FO_CLIENT_SECRET": "${input:client_secret}",
"D365FO_TENANT_ID": "${input:tenant_id}"
}
}
},
"inputs": [
{
"id": "tenant_id",
"type": "promptString",
"description": "Azure AD Tenant ID for D365 F&O authentication",
"password": true
},
{
"id": "client_id",
"type": "promptString",
"description": "Azure AD Client ID for D365 F&O authentication",
"password": true
},
{
"id": "client_secret",
"type": "promptString",
"description": "Azure AD Client Secret for D365 F&O authentication",
"password": true
}
]
}
Option 3: Docker Integration For containerized environments and enhanced isolation:
{
"servers": {
"d365fo-fastmcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"d365fo-mcp:/home/mcp_user/",
"-e",
"D365FO_CLIENT_ID=${input:client_id}",
"-e",
"D365FO_CLIENT_SECRET=${input:client_secret}",
"-e",
"D365FO_TENANT_ID=${input:tenant_id}",
"ghcr.io/mafzaal/d365fo-client:latest"
],
"env": {
"D365FO_LOG_LEVEL": "DEBUG",
"D365FO_CLIENT_ID": "${input:client_id}",
"D365FO_CLIENT_SECRET": "${input:client_secret}",
"D365FO_TENANT_ID": "${input:tenant_id}"
}
}
},
"inputs": [
{
"id": "tenant_id",
"type": "promptString",
"description": "Azure AD Tenant ID for D365 F&O authentication",
"password": true
},
{
"id": "client_id",
"type": "promptString",
"description": "Azure AD Client ID for D365 F&O authentication",
"password": true
},
{
"id": "client_secret",
"type": "promptString",
"description": "Azure AD Client Secret for D365 F&O authentication",
"password": true
}
]
}
Benefits of Docker approach:
- Complete environment isolation and reproducibility
- No local Python installation required
- Consistent runtime environment across different systems
- Automatic dependency management with pre-built image
- Enhanced security through containerization
- Persistent data storage via Docker volume (
d365fo-mcp)
Prerequisites:
- Docker installed and running
- Access to Docker Hub or GitHub Container Registry
- Network access for pulling the container image
Claude Desktop Integration
FastMCP Server: Add to your Claude Desktop configuration:
{
"mcpServers": {
"d365fo-fastmcp": {
"command": "uvx",
"args": [
"--from",
"d365fo-client",
"d365fo-fastmcp-server"
],
"env": {
"D365FO_BASE_URL": "https://your-environment.dynamics.com",
"D365FO_LOG_LEVEL": "INFO"
}
}
}
}
Traditional MCP Server (Alternative):
{
"mcpServers": {
"d365fo": {
"command": "uvx",
"args": [
"--from",
"d365fo-client",
"d365fo-fastmcp-server"
],
"env": {
"D365FO_BASE_URL": "https://your-environment.dynamics.com",
"D365FO_LOG_LEVEL": "INFO"
}
}
}
}
Benefits of uvx approach:
- Always uses the latest version from the repository
- No local installation required
- Automatic dependency management
- Works across different environments
Web Integration with FastMCP
The FastMCP server provides HTTP and SSE transports for web application integration:
HTTP Transport for Web APIs
import aiohttp
import json
async def call_d365fo_api():
"""Example: Using HTTP transport for web API integration"""
# Start FastMCP server with HTTP transport
# d365fo-fastmcp-server --transport http --port 8000
mcp_request = {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "d365fo_query_entities",
"arguments": {
"entityName": "CustomersV3",
"top": 10,
"select": ["CustomerAccount", "Name"]
}
}
}
async with aiohttp.ClientSession() as session:
async with session.post(
"http://localhost:8000/mcp",
json=mcp_request,
headers={"Content-Type": "application/json"}
) as response:
result = await response.json()
print(json.dumps(result, indent=2))
SSE Transport for Real-time Applications
// Example: JavaScript client for real-time D365FO data
// Start FastMCP server: d365fo-fastmcp-server --transport sse --port 8001
const eventSource = new EventSource('http://localhost:8001/sse');
eventSource.onmessage = function(event) {
const data = JSON.parse(event.data);
console.log('Received D365FO data:', data);
// Handle real-time updates from D365FO
if (data.method === 'notification') {
updateDashboard(data.params);
}
};
// Send MCP requests via SSE
function queryCustomers() {
const request = {
jsonrpc: "2.0",
id: Date.now(),
method: "tools/call",
params: {
name: "d365fo_search_entities",
arguments: {
pattern: "customer",
limit: 50
}
}
};
fetch('http://localhost:8001/sse/send', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify(request)
});
}
Alternative: Programmatic Usage
from d365fo_client.mcp import D365FOMCPServer
# Create and run server with custom configuration
config = {
"default_environment": {
"base_url": "https://your-environment.dynamics.com",
"use_default_credentials": True
}
}
server = D365FOMCPServer(config)
await server.run()
Custom MCP Clients
Connect using any MCP-compatible client library:
from mcp import Client
async with Client("d365fo-fastmcp-server") as client:
# Discover available tools
tools = await client.list_tools()
# Execute operations
result = await client.call_tool(
"d365fo_query_entities",
{"entityName": "Customers", "top": 5}
)
Docker Deployment
For containerized environments and production deployments:
Pull the Docker Image:
# Pull from GitHub Container Registry
docker pull ghcr.io/mafzaal/d365fo-client:latest
# Or pull a specific version
docker pull ghcr.io/mafzaal/d365fo-client:v0.2.3
Standalone Docker Usage:
# Run MCP server with environment variables
docker run --rm -i \
-e D365FO_BASE_URL="https://your-environment.dynamics.com" \
-e D365FO_CLIENT_ID="your-client-id" \
-e D365FO_CLIENT_SECRET="your-client-secret" \
-e D365FO_TENANT_ID="your-tenant-id" \
-e D365FO_LOG_LEVEL="INFO" \
-v d365fo-mcp:/home/mcp_user/ \
ghcr.io/mafzaal/d365fo-client:latest
# Run CLI commands with Docker
docker run --rm -it \
-e D365FO_BASE_URL="https://your-environment.dynamics.com" \
-e D365FO_CLIENT_ID="your-client-id" \
-e D365FO_CLIENT_SECRET="your-client-secret" \
-e D365FO_TENANT_ID="your-tenant-id" \
ghcr.io/mafzaal/d365fo-client:latest \
d365fo-client entities --limit 10
Docker Compose Example:
version: '3.8'
services:
d365fo-mcp:
image: ghcr.io/mafzaal/d365fo-client:latest
environment:
- D365FO_BASE_URL=https://your-environment.dynamics.com
- D365FO_CLIENT_ID=${D365FO_CLIENT_ID}
- D365FO_CLIENT_SECRET=${D365FO_CLIENT_SECRET}
- D365FO_TENANT_ID=${D365FO_TENANT_ID}
- D365FO_LOG_LEVEL=INFO
volumes:
- d365fo-mcp:/home/mcp_user/
stdin_open: true
tty: true
volumes:
d365fo-mcp:
Docker Benefits:
- Complete environment isolation and reproducibility
- No local Python installation required
- Consistent runtime environment across different systems
- Built-in dependency management
- Enhanced security through containerization
- Persistent data storage via Docker volumes
- Easy integration with orchestration platforms (Kubernetes, Docker Swarm)
Architecture Benefits
For AI Assistants
- Standardized Interface: Consistent MCP protocol access to D365 F&O
- Rich Metadata: Self-describing entities and operations
- Type Safety: Schema validation for all operations
- Error Context: Detailed error information for troubleshooting
For Developers
- Minimal Integration: Standard MCP client libraries
- Comprehensive Coverage: Full D365 F&O functionality exposed
- Performance Optimized: Efficient connection and caching strategies
- Well Documented: Complete API documentation and examples
For Organizations
- Secure Access: Enterprise-grade authentication (Azure AD, Managed Identity)
- Audit Logging: Complete operation tracking and monitoring
- Scalable Design: Connection pooling and session management
- Maintenance Friendly: Clear architecture and comprehensive test coverage
Troubleshooting
Common Issues
Connection Failures
# Test connectivity
d365fo-client version app --base-url https://your-environment.dynamics.com
# Check logs
tail -f ~/.d365fo-mcp/logs/mcp-server.log
Authentication Issues
# Verify Azure CLI authentication
az account show
# Test with explicit credentials
export D365FO_CLIENT_ID="your-client-id"
# ... set other variables
d365fo-fastmcp-server
Performance Issues
# Enable debug logging
export D365FO_LOG_LEVEL="DEBUG"
# Adjust connection settings
export D365FO_CONNECTION_TIMEOUT="120"
export D365FO_MAX_CONCURRENT_REQUESTS="5"
Getting Help
- Logs: Check
~/.d365fo-mcp/logs/mcp-server.logfor detailed error information - Environment: Use
d365fo_get_environment_infotool to check system status - Documentation: See MCP Implementation Summary for technical details
- Issues: Report problems at GitHub Issues
MCP Tools
The server provides 49 comprehensive tools organized into functional categories:
Connection & Environment Tools (2 tools)
d365fo_test_connection- Test connectivity and authentication with performance metrics and error diagnosticsd365fo_get_environment_info- Get comprehensive environment details including versions, configurations, and capabilities
CRUD Operations Tools (7 tools)
d365fo_query_entities- Simplified OData querying with 'eq' filtering, wildcard patterns, field selection, and paginationd365fo_get_entity_record- Retrieve specific records by key with expansion options and ETag supportd365fo_create_entity_record- Create new entity records with validation and business logic executiond365fo_update_entity_record- Update existing records with partial updates and optimistic concurrency controld365fo_delete_entity_record- Delete entity records with referential integrity checking and cascading rulesd365fo_call_action- Execute OData actions and functions for complex business operationsd365fo_call_json_service- Call generic JSON service endpoints with parameter support and response handling
Metadata Discovery Tools (6 tools)
d365fo_search_entities- Search entities by pattern with category filtering and full-text search capabilitiesd365fo_get_entity_schema- Get detailed entity schemas with properties, relationships, and label resolutiond365fo_search_actions- Search available OData actions with binding type and parameter informationd365fo_search_enumerations- Search system enumerations with keyword-based filteringd365fo_get_enumeration_fields- Get detailed enumeration member information with multi-language supportd365fo_get_installed_modules- Retrieve information about installed modules and their configurations
Label Management Tools (2 tools)
d365fo_get_label- Get single label text by ID with multi-language support and fallback optionsd365fo_get_labels_batch- Get multiple labels efficiently with batch processing and performance optimization
Profile Management Tools (14 tools)
d365fo_list_profiles- List all configured D365FO environment profiles with status informationd365fo_get_profile- Get detailed configuration information for specific profilesd365fo_create_profile- Create new environment profiles with comprehensive authentication optionsd365fo_update_profile- Modify existing profile configurations with partial update supportd365fo_delete_profile- Remove environment profiles with proper cleanup and validationd365fo_set_default_profile- Designate a specific profile as the default for operationsd365fo_get_default_profile- Retrieve information about the currently configured default profiled365fo_validate_profile- Validate profile configurations for completeness and security complianced365fo_test_profile_connection- Test connectivity and authentication for specific profilesd365fo_clone_profile- Clone existing profiles with customization options for new environmentsd365fo_search_profiles- Search profiles by pattern with filtering and sorting capabilitiesd365fo_get_profile_names- Get simplified list of available profile names for quick referenced365fo_import_profiles- Import profile configurations from external sources or backupsd365fo_export_profiles- Export profile configurations for backup or deployment purposes
Database Analysis Tools (4 tools)
d365fo_execute_sql_query- Execute SELECT queries against metadata database with security validationd365fo_get_database_schema- Get comprehensive database schema information including relationshipsd365fo_get_table_info- Get detailed information about specific database tables with sample datad365fo_get_database_statistics- Generate database statistics and analytics for performance monitoring
Synchronization Tools (5 tools)
d365fo_start_sync- Initiate metadata synchronization with various strategies and session trackingd365fo_get_sync_progress- Monitor detailed progress of sync sessions with time estimatesd365fo_cancel_sync- Cancel running sync sessions with graceful cleanupd365fo_list_sync_sessions- List all active sync sessions with status and progress informationd365fo_get_sync_history- Get history of completed sync sessions with success/failure status and statistics
SRS Reporting Tools (6 tools)
d365fo_download_srs_report- Download SQL Server Reporting Services (SRS) reports with parameter supportd365fo_download_sales_confirmation- Download sales confirmation reports in various formatsd365fo_download_purchase_order- Download purchase order documents with formatting optionsd365fo_download_customer_invoice- Download customer invoice reports with customizationd365fo_download_free_text_invoice- Download free text invoice documentsd365fo_download_debit_credit_note- Download debit and credit note reports
Performance Monitoring Tools (3 tools)
d365fo_get_server_performance- Get server performance metrics and statisticsd365fo_get_server_config- Get server configuration information and system settingsd365fo_reset_performance_stats- Reset performance statistics and counters for fresh monitoring
📖 For detailed information about all MCP tools including usage examples and best practices, see the Comprehensive MCP Tools Introduction.
🤖 For AI agents and assistants, see the AI Agent Guide for structured workflows, best practices, and automation patterns.
MCP Resources
The server exposes four types of resources for discovery and access:
Entity Resources
Access entity metadata and sample data:
d365fo://entities/CustomersV3 # Customer entity with metadata and sample data
d365fo://entities/SalesOrders # Sales order entity information
d365fo://entities/Products # Product entity details
Metadata Resources
Access system-wide metadata:
d365fo://metadata/entities # All data entities metadata (V2 cache)
d365fo://metadata/actions # Available OData actions
d365fo://metadata/enumerations # System enumerations
d365fo://metadata/labels # System labels and translations
Environment Resources
Access environment status and information:
d365fo://environment/status # Environment health and connectivity
d365fo://environment/version # Version information (app, platform, build)
d365fo://environment/cache # Cache status and statistics V2
Query Resources
Access predefined and templated queries:
d365fo://queries/customers_recent # Recent customers query template
d365fo://queries/sales_summary # Sales summary query with parameters
Database Resources (New in V2)
Access metadata database queries:
d365fo://database/entities # SQL-based entity searches with FTS5
d365fo://database/actions # Action discovery with metadata
d365fo://database/statistics # Cache and performance statistics
Usage Examples
Basic Tool Execution
{
"tool": "d365fo_query_entities",
"arguments": {
"entityName": "CustomersV3",
"select": ["CustomerAccount", "Name", "Email"],
"filter": "CustomerGroup eq 'VIP'",
"top": 10
}
}
Entity Schema Discovery
{
"tool": "d365fo_get_entity_schema",
"arguments": {
"entityName": "CustomersV3",
"includeProperties": true,
"resolveLabels": true,
"language": "en-US"
}
}
Environment Information
{
"tool": "d365fo_get_environment_info",
"arguments": {}
}
Authentication & Configuration
Default Credentials (Recommended)
Uses Azure Default Credential chain (Managed Identity, Azure CLI, etc.):
export D365FO_BASE_URL="https://your-environment.dynamics.com"
# No additional auth environment variables needed
d365fo-fastmcp-server
Explicit Credentials
For service principal authentication:
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CLIENT_ID="your-client-id"
export D365FO_CLIENT_SECRET="your-client-secret"
export D365FO_TENANT_ID="your-tenant-id"
d365fo-fastmcp-server
Azure Key Vault Integration (New in v0.2.3)
For secure credential storage using Azure Key Vault:
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CREDENTIAL_SOURCE="keyvault"
export D365FO_KEYVAULT_URL="https://your-keyvault.vault.azure.net/"
d365fo-fastmcp-server
Advanced Configuration
New in v0.3.0: Comprehensive environment variable management with type safety and validation using Pydantic settings.
Create a configuration file or set additional environment variables:
# === Core D365FO Connection Settings ===
export D365FO_BASE_URL="https://your-environment.dynamics.com"
export D365FO_CLIENT_ID="your-client-id"
export D365FO_CLIENT_SECRET="your-client-secret"
export D365FO_TENANT_ID="your-tenant-id"
# === Logging Configuration ===
export D365FO_LOG_LEVEL="DEBUG" # DEBUG, INFO, WARNING, ERROR, CRITICAL
export D365FO_LOG_FILE="/custom/path/server.log" # Custom log file path
# === MCP Server Transport Settings (v0.3.0+) ===
export D365FO_MCP_TRANSPORT="stdio" # stdio, sse, http, streamable-http
export D365FO_MCP_HTTP_HOST="0.0.0.0" # HTTP host (default: 127.0.0.1)
export D365FO_MCP_HTTP_PORT="8000" # HTTP port (default: 8000)
export D365FO_MCP_HTTP_STATELESS="true" # Enable stateless mode
export D365FO_MCP_HTTP_JSON="true" # Enable JSON response mode
# === Cache and Performance Settings ===
export D365FO_CACHE_DIR="/custom/cache/path" # General cache directory
export D365FO_META_CACHE_DIR="/custom/metadata/cache" # Metadata cache directory
export D365FO_LABEL_CACHE="true" # Enable label caching (default: true)
export D365FO_LABEL_EXPIRY="1440" # Label cache expiry in minutes (24 hours)
export D365FO_USE_CACHE_FIRST="true" # Use cache before API calls
# === Connection and Performance Tuning ===
export D365FO_TIMEOUT="60" # General timeout in seconds
export D365FO_MCP_MAX_CONCURRENT_REQUESTS="10" # Max concurrent requests
export D365FO_MCP_REQUEST_TIMEOUT="30" # Request timeout in seconds
export D365FO_VERIFY_SSL="true" # Verify SSL certificates
# === MCP Authentication Settings (Advanced) ===
export D365FO_MCP_AUTH_CLIENT_ID="your-mcp-client-id"
export D365FO_MCP_AUTH_CLIENT_SECRET="your-mcp-client-secret"
export D365FO_MCP_AUTH_TENANT_ID="your-mcp-tenant-id"
export D365FO_MCP_AUTH_BASE_URL="http://localhost:8000"
export D365FO_MCP_AUTH_REQUIRED_SCOPES="User.Read,email,openid,profile"
# === Debug Settings ===
export DEBUG="true" # Enable debug mode
Environment File Support
