mcp-business-central 1.0.9

MCP Server for Microsoft Dynamics 365 Business Central

🏢 Microsoft Dynamics 365 Business Central MCP Server

A MCP Server for Microsoft Dynamics 365 Business Central with OAuth2 authentication and API v2.0 endpoints. Built by Dmitry Katson, Microsoft AI & Business Central MVP, enabling AI agents to seamlessly interact with Business Central data.

Please note that this project is actively maintained and may receive updates to enhance functionality and compatibility.

�� Table of Contents

1. 🎯 Overview
2. 🛠️ Currently Supported Tools
3. 🔌 Installation & Getting Started
4. ⚙️ Configuration
5. ❓ Troubleshooting
6. 📚 Additional Resources
7. 👨‍💻 Author
8. 📄 License

🎯 Overview

✨ Example Prompts: Your Business Central Assistant

Your AI assistant can seamlessly interact with your Business Central environment using these advanced tools. Try asking questions like:

• "List all open purchase orders for the last month"
• "Which customers have not placed an order in the past 90 days?"
• "Show me the top 5 selling items by revenue this quarter"
• "What are the outstanding vendor invoices over $10,000?"
• "Find all sales orders awaiting shipment"
• "Which items are below their reorder point?"
• "Get the approval status of all posted purchase invoices"

Everything exposed by your Business Central APIs—whether standard or custom—is accessible through this MCP server.

📊 Key Capabilities

• 🔐 OAuth2 Authentication: Secure Azure AD integration with Business Central
• 🏢 Auto Company Discovery: Automatic company detection and switching
• 📊 Full CRUD Operations: Complete entity management capabilities
• 🔍 Schema Discovery: Dynamic field and relationship exploration
• ⚡ API v2.0: Latest Business Central OData endpoints
• 🧩 Clean Architecture: Professional, scalable, and maintainable design

🛠️ Currently Supported Tools

Tool Name	Description	Input Parameters
list_companies	Discover all available companies in your BC environment	None
set_active_company	Set the active company for subsequent operations	company_id (string): UUID of the company
get_active_company	Get information about the currently active company	None
list_resources	List all available Business Central resources/entities	None
get_odata_metadata	Smart metadata search - find entities, properties, relationships by search term	search (string): Search term search_type (string): Type filter include_properties (bool): Include properties include_relationships (bool): Include relationships
get_resource_schema	Get detailed schema and field information for an entity	resource (string): Entity name company_id (string, optional): Company UUID
list_records	List entity records with advanced filtering, sorting, and pagination	resource (string): Entity name filter (string, optional): OData filter orderby (string, optional): Sort order select (string, optional): Field selection expand (string, optional): Related entities top (int, optional): Record limit skip (int, optional): Records to skip

🔌 Installation & Getting Started

The Business Central MCP Server supports installation across multiple clients. Choose your preferred client below for streamlined setup.

▶️ Getting Started

Follow these steps to get your Business Central MCP Server up and running:

1. 📦 Install Python & Package

   • Ensure Python 3.8+ is installed on your system
   • Install the MCP server: see installation commands
   • Verify installation works: verification steps

2. 🔐 Set up Azure Authentication

   • Create Azure AD app registration: detailed Azure setup
   • Configure Business Central API permissions
   • Generate client secret and note required values

3. 🔧 Add to Your MCP Client

   • Configure your preferred client: client configuration table

4. 🚀 Test the Connection

   • Restart your MCP client completely for changes to take effect
   • Try example prompts:
     • "Show me all customers from Business Central"
     • "List available Business Central entities"
     • "What companies are available in my Business Central environment?"
   • Explore common Business Central entities like customers, vendors, items, and sales orders

💡 Tip: Once connected, you can ask about any Business Central entity or use natural language to query your business data!

Need help? Check our troubleshooting section for common issues and solutions.

📦 Installation

Prerequisites

Python 3.8+ Required - The MCP server requires Python to be installed on your system.

Operating System	Installation Method
Windows	Python Installation Steps 1. Download Python from python.org 2. Important: Check "Add Python to PATH" during installation 3. Verify installation: python --version pip --version 4. If pip is not recognized, try: python -m pip --version
macOS	Python Installation Steps Option 1 - Official Python: Download from python.org Option 2 - Homebrew: brew install python Option 3 - Built-in (macOS 12.3+): Python 3 is pre-installed
Linux	Python Installation Steps Ubuntu/Debian: sudo apt update sudo apt install python3 python3-pip CentOS/RHEL/Fedora: sudo yum install python3 python3-pip Arch Linux: sudo pacman -S python python-pip

Install MCP Business Central

Once Python is installed, install the MCP server:

# Windows
pip install mcp-business-central
# or if pip is not in PATH:
python -m pip install mcp-business-central

# macOS/Linux  
pip3 install mcp-business-central
# or
python3 -m pip install mcp-business-central

Verify Installation

# Windows
python -m mcp_business_central --help

# macOS/Linux
python3 -m mcp_business_central --help

⚙️ Configuration

🔐 Azure AD Setup

1. Create Azure AD App Registration

   • Navigate to Azure Portal → Azure Active Directory → App registrations
   • Click "New registration"
   • Provide a meaningful name (e.g., "Business Central MCP Server")

2. Configure API Permissions

   • Go to "API permissions"
   • Add permission → Microsoft APIs → Dynamics 365 Business Central
   • Select Financials.ReadWrite.All (Application permission)
   • Grant admin consent for your organization

3. Create Client Secret

   • Go to "Certificates & secrets"
   • Click "New client secret"
   • Copy the secret value (you won't see it again!)

4. Note Required Values

   • Application (client) ID
   • Directory (tenant) ID
   • Client secret value

🔧 Client Configuration

Client	Configuration	MCP Guide
Claude Desktop	View Configuration Location: • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json • Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: { "mcpServers": { "businesscentral": { "command": "python3", "args": ["-m", "mcp_business_central"], "env": { "BC_TENANT_ID": "your-tenant-id", "BC_CLIENT_ID": "your-client-id", "BC_CLIENT_SECRET": "your-client-secret", "BC_ENVIRONMENT": "production" } } } } Windows: { "mcpServers": { "businesscentral": { "command": "python", "args": ["-m", "mcp_business_central"], "env": { "BC_TENANT_ID": "your-tenant-id", "BC_CLIENT_ID": "your-client-id", "BC_CLIENT_SECRET": "your-client-secret", "BC_ENVIRONMENT": "production" } } } }	Claude Desktop MCP Guide
VS Code	View Configuration Install the MCP extension and add to your MCP configuration: { "businesscentral": { "command": "python3", "args": ["-m", "mcp_business_central"], "env": { "BC_TENANT_ID": "your-tenant-id", "BC_CLIENT_ID": "your-client-id", "BC_CLIENT_SECRET": "your-client-secret", "BC_ENVIRONMENT": "production" } } }	VS Code MCP Official Guide
Cursor IDE	View Configuration Add to your Cursor MCP settings: { "businesscentral": { "command": "python3", "args": ["-m", "mcp_business_central"], "env": { "BC_TENANT_ID": "your-tenant-id", "BC_CLIENT_ID": "your-client-id", "BC_CLIENT_SECRET": "your-client-secret", "BC_ENVIRONMENT": "production" } } }	Cursor MCP Official Guide
Windsurf	View Configuration Add to your Windsurf MCP configuration: { "businesscentral": { "command": "python3", "args": ["-m", "mcp_business_central"], "env": { "BC_TENANT_ID": "your-tenant-id", "BC_CLIENT_ID": "your-client-id", "BC_CLIENT_SECRET": "your-client-secret", "BC_ENVIRONMENT": "production" } } }	Windsurf MCP Guide

❓ Troubleshooting

💻 System Prompt

For optimal tool usage, add this system prompt to encourage your AI assistant to use Business Central tools:

## Business Central Integration

You have access to MCP tools for Microsoft Dynamics 365 Business Central. These tools allow you to:
- Query customer, vendor, and item data
- Access financial information and sales orders
- Explore entity schemas and relationships
- Manage company contexts

When handling questions about business data, ERP operations, or financial information, use these Business Central tools to provide accurate, real-time information from the user's Business Central environment.

⚠️ Common Issues

Issue	Possible Solution
"pip is not recognized" (Windows)	• Python not installed or not in PATH • Reinstall Python with "Add to PATH" checked • Use python -m pip instead of pip • Restart command prompt after Python installation
"python: command not found"	• Python not installed • On macOS/Linux, try python3 instead of python • Install Python from official website or package manager
Authentication Errors	• Verify Azure AD app permissions • Check tenant/client ID and secret • Ensure admin consent is granted • Confirm Financials.ReadWrite.All permission
API Access Issues	• Confirm Business Central environment access • Verify correct entity names (case-sensitive) • Use list_resources to see available entities • Check environment parameter (production vs sandbox)
Connection Timeouts	• Verify network connectivity to Business Central • Check if Business Central service is online • Increase timeout settings if needed
Empty Results	• Use get_resource_schema to check available fields • Verify filter syntax (OData v4.0) • Check company selection with get_active_company
Tool Not Appearing	• Restart your MCP client completely • Verify Python installation and package • Check environment variables are set correctly

🆘 Getting Support

• Create an issue
• Join discussions
• Contact the author

📚 Additional Resources

• Microsoft Dynamics 365 Business Central Documentation
• Business Central Web API Reference
• Model Context Protocol Specification
• Azure AD App Registration Guide

👨‍💻 Author

Dmitry Katson - GitHub | Website

🏆 Microsoft AI & Business Central MVP
🏆 Contribution Hero 2024
🌐 Creator of CentralQ.ai - AI search for Business Central community

📄 License

MIT License - Copyright (c) 2025 Dmitry Katson