Python Client Library for D365FO - MCP Server: OData & AI Assistant Integration

Explore

D365fo Client

Developer tools Finance .Python

rating : 2.5 points

downloads : 7.0K

update time : 2025-12-29

Open Site

Installation

Copy the following command to your Client for 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"
      }
    }
  }
}

{
  "mcpServers": {
    "d365fo": {
      "command": "uvx",
      "args": [
        "--from",
        "d365fo-client",
        "d365fo-fastmcp-server"
      ],
      "env": {
        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
        "D365FO_LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: Your key is sensitive information, do not share it with anyone.

🚀 Dynamics 365 Finance & Operations MCP Server

This is a production-ready Model Context Protocol (MCP) server that unlocks the full potential of Microsoft Dynamics 365 Finance & Operations (D365 F&O) for AI assistants and other MCP-compatible tools. It enables sophisticated integration workflows through standardized protocol interactions.

🚀 Quick Start

Installation

You can install the server in multiple ways:

One-Click Installation for VS Code

Docker Installation for VS Code

Deploy to Azure Container Apps

You can deploy the MCP server as a secure, internet-accessible HTTP endpoint with OAuth or API Key authentication.

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

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

Start the Server

FastMCP Server (Recommended)

# 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

✨ Features

MCP Server 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_FILE environment 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 .env files and comprehensive environment variable documentation

Python Client Library Features

🔗 OData Client: Full CRUD operations on D365 F&O data entities with composite key support
📊 Metadata Management V2: Enhanced caching system with intelligent synchronization and FTS5 search
🏷️ Label Operations V2: Multilingual label caching with performance improvements and async support
🔍 Advanced Querying: Support for all OData query parameters ($select, $filter, $expand, etc.)
⚡ Action Execution: Execute bound and unbound OData actions with comprehensive parameter handling
�️ JSON Services: Generic access to D365 F&O JSON service endpoints (/api/services pattern)
�🔒 Authentication: Azure AD integration with default credentials, service principal, and Azure Key Vault support
💾 Intelligent Caching: Cross-environment cache sharing with module-based version detection
🌐 Async/Await: Modern async/await patterns with optimized session management
📝 Type Hints: Full type annotation support with enhanced data models
🤖 MCP Server: Production-ready Model Context Protocol server with 49 tools and 4 resource types
🖥️ Comprehensive CLI: Hierarchical command-line interface for all D365 F&O operations
🧪 Multi-tier Testing: Mock, sandbox, and live integration testing framework (17/17 tests passing)
📋 Metadata Scripts: PowerShell and Python utilities for entity, enumeration, and action discovery
🔐 Enhanced Credential Management: Support for Azure Key Vault and multiple credential sources
📊 Advanced Sync Management: Session-based synchronization with detailed progress tracking
🔧 NEW v0.3.0: Pydantic settings model with type-safe environment variable validation
📂 NEW v0.3.0: Custom log file path support and flexible logging configuration
🔄 NEW v0.3.0: Automatic legacy configuration migration and compatibility layer

💻 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": {}
}

Web Integration with FastMCP

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)
    });
}

Python Client Basic Usage

import asyncio
from d365fo_client import D365FOClient, FOClientConfig

async def main():
    # Simple configuration with default credentials
    config = FOClientConfig(
        base_url="https://your-fo-environment.dynamics.com",
        use_default_credentials=True  # Uses Azure Default Credential
    )
    
    async with D365FOClient(config) as client:
        # Test connection
        if await client.test_connection():
            print("✅ Connected successfully!")
        
        # Get environment information
        env_info = await client.get_environment_info()
        print(f"Environment: {env_info.application_version}")
        
        # Search for entities (uses metadata cache v2)
        customer_entities = await client.search_entities("customer")
        print(f"Found {len(customer_entities)} customer entities")
        
        # Get customers with query options
        from d365fo_client import QueryOptions
        options = QueryOptions(
            select=["CustomerAccount", "Name", "SalesCurrencyCode"],
            top=10,
            orderby=["Name"]
        )
        
        customers = await client.get_data("/data/CustomersV3", options)
        print(f"Retrieved {len(customers['value'])} customers")

if __name__ == "__main__":
    asyncio.run(main())

📚 Documentation

MCP Tools Documentation

For detailed information about all MCP tools including usage examples and best practices, see the Comprehensive MCP Tools Introduction.

AI Agent Guide

For AI agents and assistants, see the AI Agent Guide for structured workflows, best practices, and automation patterns.

🔧 Technical Details

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

Configuration Options

Option	Type	Default	Description
`base_url`	str	Required	D365 F&O base URL
`client_id`	str	None	Azure AD client ID
`client_secret`	str	None	Azure AD client secret
`tenant_id`	str	None	Azure AD tenant ID
`use_default_credentials`	bool	True	Use Azure Default Credential
`credential_source`	str	"environment"	Credential source: "environment", "keyvault"
`keyvault_url`	str	None	Azure Key Vault URL for credential storage
`verify_ssl`	bool	False	Verify SSL certificates
`timeout`	int	30	Request timeout in seconds
`metadata_cache_dir`	str	Platform-specific user cache	Metadata cache directory
`use_label_cache`	bool	True	Enable label caching V2
`label_cache_expiry_minutes`	int	60	Label cache expiry time
`use_cache_first`	bool	False	Enable cache-first mode with background sync

Cache Directory Behavior

By default, the client uses platform-appropriate user cache directories:

Windows: %LOCALAPPDATA%\d365fo-client (e.g., C:\Users\username\AppData\Local\d365fo-client)
macOS: ~/Library/Caches/d365fo-client (e.g., /Users/username/Library/Caches/d365fo-client)
Linux: ~/.cache/d365fo-client (e.g., /home/username/.cache/d365fo-client)

You can override this by explicitly setting metadata_cache_dir:

from d365fo_client import FOClientConfig

# Use custom cache directory
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com",
    metadata_cache_dir="/custom/cache/path"
)

# Or get the default cache directory programmatically
from d365fo_client import get_user_cache_dir

cache_dir = get_user_cache_dir("my-app")  # Platform-appropriate cache dir
config = FOClientConfig(
    base_url="https://your-fo-environment.dynamics.com", 
    metadata_cache_dir=str(cache_dir)
)

📦 Installation

Install the Python Client Library

# Install from PyPI
pip install d365fo-client

# Or install from source
git clone https://github.com/mafzaal/d365fo-client.git
cd d365fo-client
uv sync  # Installs with exact dependencies from uv.lock

# Or use Docker (no local installation required)
docker pull ghcr.io/mafzaal/d365fo-client:latest

# Run 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" \
  -v d365fo-mcp:/home/mcp_user/ \
  ghcr.io/mafzaal/d365fo-client:latest