bc-container-mcp

MCP server for Business Central Docker container management. Lets AI agents create, configure, and operate BC containers through natural language. No Docker Desktop, no BcContainerHelper required.

The AI agent version of bc-docker-manager, a VS Code extension for BC container management.

What This Is

Every BC developer eventually needs a local container for development, testing, and debugging. The traditional options involve either Docker Desktop (a 1GB+ GUI application that requires a paid subscription for business use) or BcContainerHelper (a PowerShell module with dozens of its own dependencies). Neither of these integrates naturally with AI agents.

This server exposes 54 MCP tools that any AI agent can call by name. You tell your agent "create a BC 28 sandbox container for Australia with 8GB memory" and it figures out the right artifact URL, pulls the image, runs the container, and waits for BC to be ready. No manual Docker commands, no PowerShell module setup, no Docker Desktop license.

The key difference from BcContainerHelper is the execution model. BcContainerHelper is designed for human scripting: it wraps everything in a single high-level function with a hundred parameters. This server speaks directly to the Docker CLI and executes PowerShell inside the container through docker exec. The only prerequisites are Docker Engine (the Windows service, not the Desktop app) and Node.js.

Requirements

• Windows 10/11 or Windows Server 2019+ with Hyper-V capable hardware.

That is it. The installer handles everything else automatically:

Dependency	How It Is Handled
Node.js 22.5+	Auto-installed via winget if missing or outdated
Docker Engine	Auto-downloaded (parallel chunked) and registered as a Windows service, no Docker Desktop needed
Windows Containers feature	Auto-enabled (prompts for elevation if needed)
Hyper-V	Auto-enabled (prompts for elevation if needed)
npm packages	Installed during build step
TypeScript compilation	Runs automatically
MCP client registration	Auto-registered in Copilot CLI, VS Code, VS Code Insiders, Cursor, and Claude Desktop

No manual downloads. No Docker Desktop license. No BcContainerHelper.

Quick Start

Clone the repo and run the installer:

git clone https://github.com/learnbeyondbc/bc-container-mcp.git
cd bc-container-mcp
.\install.ps1

The installer checks your Node.js version, installs npm dependencies, compiles the TypeScript source, and registers the MCP server in both GitHub Copilot CLI and VS Code. You do not need to touch any config files manually.

Restart your AI client, then ask:

Use the bc-container MCP to check my environment

Tools Reference (54 tools)

Container Lifecycle (10 tools)

Tool	Description	Key Parameters
list_containers	List BC containers with version, country, and status. Auto-starts Docker if not running. Hints about exited containers needing cleanup.	bcOnly (default: true)
container_info	Detailed container info: version, health, ports, server instance, IP, web client URL. Warns if hosts file is stale.	containerName
create_container	Create a BC container via direct docker run. Resolves artifact URL from Microsoft CDN, pulls image if not cached, detects early failures (corrupt downloads, OOM), suggests naming convention.	containerName, version, country, artifactUrl, auth, username, password, memoryLimit, image, isolation, showProgress
start_container	Start a stopped container. Auto-updates the hosts file if the container IP changed.	containerName
stop_container	Stop a running container.	containerName
restart_container	Restart a container. Auto-updates the hosts file if the IP changed.	containerName
remove_container	Remove a container. Requires confirmName matching containerName to prevent accidental deletion.	containerName, confirmName
get_logs	Get Docker logs for a container.	containerName, tail (default: 100)
pull_image	Pre-pull a BC base image. BC images are 5-15 GB; pulling takes 5-20 minutes. create_container does this automatically, but you can trigger it in advance.	image
monitor_container	Open a live monitoring window showing health, state, and recent logs in a separate terminal. Refreshes automatically.	containerName, refreshInterval (default: 10)

Creating a container: tell your assistant in plain English. It stops existing containers, resolves the artifact URL, and creates the new one:

Listing containers with status and annotations: works in both VS Code and the terminal:

BC Operations (10 tools)

Tool	Description	Key Parameters
wait_for_ready	Wait for a BC container to become healthy and responsive. Returns web client URL and credentials on success.	containerName, timeoutSeconds (default: 300)
publish_app	Publish an .app file to a container. Uses chunked base64 transfer (Hyper-V compatible).	containerName, appPath, skipVerification, syncMode, install, upgrade
upload_license	Import a .flf or .bclicense file and restart the service tier.	containerName, licensePath
add_user	Add a BC user with a permission set. Validates password complexity before calling BC.	containerName, username, password, permissionSet (default: SUPER)
add_test_users	Create the three standard test users (ESSENTIAL, PREMIUM, TEAMMEMBER) with password P@ssw0rd.	containerName
update_user	Update an existing user's password or permission set.	containerName, username, password, permissionSet
backup_database	Back up the BC database to a .bak file on the host. Auto-detects SQL Express for compression settings.	containerName, backupPath
restore_database	Restore a .bak file into a container. Replaces the current database; requires confirmDataLoss=true.	containerName, backupPath, confirmDataLoss
install_test_toolkit	Install BC Test Toolkit apps into a container.	containerName, scope (framework or full)
list_extensions	List all published extensions in a container.	containerName

Creating a user: ask to create a user with a name and password. The agent calls add_user and confirms:

Logging in with the created user: it works immediately in the web client:

Verified in Business Central: the user has full access to the sandbox:

Development (3 tools)

Tool	Description	Key Parameters
generate_launch_json	Generate a VS Code launch.json configuration for the AL Language extension. Merges into an existing file if one already exists.	containerName, outputPath, serverInstance, authentication, port, startupObjectId, breakOnError
compile_app	Compile an AL project inside the container using alc.exe. Transfers the project in, compiles against system symbols, and returns the .app file.	containerName, projectPath, outputPath
exec_in_container	Execute a PowerShell command inside a running container. Use for ad-hoc queries or admin tasks.	containerName, command, useNavModule, timeoutSeconds

Networking (2 tools)

Tool	Description	Key Parameters
get_webclient_url	Return the BC web client URL and container IP. Also tells you if networking needs to be configured.	containerName
setup_networking	Update the Windows hosts file with the container IP and install the container SSL certificate into the Trusted Root store. Verifies certificate installation by thumbprint. Triggers a UAC elevation prompt.	containerName, hostsOnly

Artifacts (3 tools)

Tool	Description	Key Parameters
search_artifacts	Search available BC artifacts from the Microsoft CDN. Returns version numbers, release dates, and artifact URLs. Without a version filter, shows the latest build per major version. With a version filter, shows all builds for that major.	type (sandbox/onprem), country, version
list_countries	List all available country/localization codes from the BC artifact CDN.	type (sandbox/onprem)
list_versions	List all available major BC versions from the CDN.	type (sandbox/onprem), country

Bulk Operations (3 tools)

Tool	Description	Key Parameters
start_all_containers	Start all stopped BC containers. Pre-flights Docker accessibility with actionable fix guidance.	(none)
stop_all_containers	Stop all running BC containers. Pre-flights Docker accessibility with actionable fix guidance.	(none)
remove_all_containers	Remove all stopped BC containers. Only removes containers that are not running. Requires confirmRemoval=true.	confirmRemoval

Images and Volumes (5 tools)

Tool	Description	Key Parameters
list_images	List all local Docker images with repository, tag, and size.	(none)
remove_image	Remove a local Docker image by ID or repository:tag.	imageRef
list_volumes	List all Docker volumes on the host.	(none)
create_volume	Create a new Docker volume. Volumes persist data across container rebuilds.	name
remove_volume	Remove a Docker volume. The volume must not be in use unless force=true.	name, force

Profiles (4 tools)

Tool	Description	Key Parameters
save_profile	Save a named preset of container creation parameters. Persists in %APPDATA%\bc-container-mcp\profiles.json.	name, memory, isolation, auth, country, dns, licensePath
load_profile	Load a saved profile. Returns the stored settings to pass to create_container.	name
list_profiles	List all saved profiles.	(none)
delete_profile	Delete a saved profile.	name

Annotations (4 tools)

Tool	Description	Key Parameters
set_container_note	Attach a free-text note to a container (e.g., "BC 26 upgrade testing"). Persists in %APPDATA%\bc-container-mcp\annotations.json.	containerName, note
set_container_tags	Attach searchable tags to a container (e.g., ["dev", "bc28", "au"]).	containerName, tags
get_container_annotations	Get the note and tags for a container, or list all annotated containers if no name is given.	containerName (optional)
clear_container_annotations	Remove all notes and tags from a container.	containerName

Configuration (3 tools)

Tool	Description	Key Parameters
configure_defaults	Save preferred defaults for create_container (memory, country, auth, username, image, isolation). Persists across sessions. Password is intentionally not persisted; use the DEFAULT_PASSWORD env var instead.	memory, country, auth, username, image, isolation
show_defaults	Show current effective defaults for all create_container settings, including the default password. Shows which source each value comes from (user config, env var, or built-in).	(none)
reset_defaults	Delete all saved user preferences and revert to built-in defaults. Requires confirm="yes".	confirm

Diagnostics (7 tools)

Tool	Description	Key Parameters
doctor	Run a full environment check: Node.js version, Docker CLI, Docker Engine state, Windows containers mode, BC container count, PowerShell 5 availability, BC artifacts CDN connectivity.	(none)
setup_environment	Check Hyper-V and Windows Containers feature state. With fix=true, attempts to enable missing features and create daemon.json via elevated PowerShell.	fix
start_docker_engine	Start the Docker Engine Windows service. Tries the docker service (standalone Docker Engine) first, then com.docker.service (Docker Desktop daemon). Polls until ready or times out.	waitSeconds (default: 60)
container_stats	Get real-time CPU, memory, network I/O, and disk I/O stats for a container.	name
get_event_log	Get BC and SQL event log entries from inside a container.	name, count (default: 50)
get_nst_settings	Read NST (NAV Server) configuration settings from a container. Supports substring filter.	name, filter
set_nst_setting	Modify an NST configuration setting. Optionally restart the service tier after changing.	name, keyName, keyValue, restart

Usage Examples

These are the kinds of prompts you can give directly to your AI agent. No special syntax required.

"Create a BC container named bc28au with version 28, country au, 8GB memory"

"List all my running BC containers"

"Generate a launch.json for the bc28au container in my project at C:\src\myapp"

"Compile my AL project at C:\src\myapp in the bc28au container"

"What are the default credentials for BC containers?"

"Search for the latest BC 28 sandbox artifact for Australia"

"Show me what is wrong with my BC container environment"

"Open a monitoring window for bc28au"

"Start all stopped BC containers"

Default Configuration

On the first create_container call, the server nudges you to run configure_defaults. Once saved, those preferences apply automatically to every subsequent create_container call unless you override them per-call.

The defaults priority chain, from lowest to highest: built-in defaults, then environment variables, then saved user config (%APPDATA%\bc-container-mcp\config.json), then per-call arguments.

Setting	Built-in Default	Configure with
Memory	8G	configure_defaults
Country	w1	configure_defaults
Auth mode	NavUserPassword	configure_defaults
Isolation	hyperv	configure_defaults
Username	admin	configure_defaults
Password	P@ssw0rd!	DEFAULT_PASSWORD env var

First Run Workflow

1. Clone the repo and run .\install.ps1.
2. Restart your AI client.
3. Ask the agent to run doctor to verify the environment.
4. If Docker is not running, ask the agent to run start_docker_engine.
5. If Hyper-V or Windows Containers features are missing, ask the agent to run setup_environment with fix=true and reboot.
6. Ask the agent to run search_artifacts for your target BC version and country.
7. Ask the agent to run create_container with your chosen name, version, and country.
8. Ask the agent to run wait_for_ready. BC initialization takes 3-8 minutes.
9. Ask the agent to run setup_networking. This updates the hosts file and installs the SSL certificate so the web client is reachable over HTTPS.
10. Ask the agent to run generate_launch_json for your project folder. This creates .vscode/launch.json for the AL debugger.
11. Open the browser and navigate to the web client URL returned by get_webclient_url.

Docker Deployment

Running on a Remote Server

You can host this MCP server on any Windows machine with Docker Engine. The server runs on stdio by default but can be fronted by an SSE/WebSocket transport for remote access:

# On the server
git clone https://github.com/learnbeyondbc/bc-container-mcp.git
cd bc-container-mcp
.\install.ps1

# The server is now available via stdio. For remote access,
# use an MCP proxy like mcp-proxy or expose via SSE transport.

Disk Usage

Component	Size	Notes
This MCP server	~15 MB	Node.js project + compiled JS
BC base image (ltsc2022)	5-15 GB	Pulled once, shared across containers
Each BC container	1-3 GB	Depends on BC version and data
Node.js runtime	~80 MB	Required on host

Token/Usage Pricing

This MCP server is free and open source. There are no API keys, no token-based pricing, no metered billing. Your only costs are:

• Disk space for Docker images and containers
• Your AI client's token usage when calling MCP tools (depends on your client's pricing)
• Network bandwidth for pulling BC images from Microsoft's CDN

MCP Client Configuration

Running .\install.ps1 registers the server automatically in GitHub Copilot CLI (~/.copilot/mcp-config.json) and VS Code (%APPDATA%\Code\User\mcp.json). For other clients, add the entry manually using the snippets below.

GitHub Copilot CLI

File: ~/.copilot/mcp-config.json (written automatically by the installer)

{
  "mcpServers": {
    "bc-container": {
      "tools": ["*"],
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/bc-container-mcp/dist/index.js"]
    }
  }
}

VS Code

File: %APPDATA%\Code\User\mcp.json (written automatically by the installer)

{
  "servers": {
    "bc-container": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/bc-container-mcp/dist/index.js"]
    }
  }
}

Claude Desktop

File: %APPDATA%\Claude\claude_desktop_config.json (manual)

{
  "mcpServers": {
    "bc-container": {
      "command": "node",
      "args": ["C:/path/to/bc-container-mcp/dist/index.js"]
    }
  }
}

Cursor

File: %APPDATA%\Roaming\Cursor\User\globalStorage\cursor-mcp\mcp.json (manual)

{
  "mcpServers": {
    "bc-container": {
      "command": "node",
      "args": ["C:/path/to/bc-container-mcp/dist/index.js"]
    }
  }
}

Use forward slashes in the path on all clients.

Development

npm install
npm run build          # TypeScript -> dist/
npm test               # 156 tests across 13 suites
npm run dev            # Development mode with tsx (no build step)
npm run lint           # Type-check only (tsc --noEmit)

Environment Variables

Variable	Default	Description
LOG_LEVEL	info	Log verbosity: trace, debug, info, warn, error, fatal
DOCKER_PATH	docker	Path to the Docker CLI binary if not on PATH
DEFAULT_PASSWORD	P@ssw0rd!	Default admin password for new containers
DEFAULT_MEMORY	8G	Default memory limit
DEFAULT_COUNTRY	w1	Default country code
DEFAULT_AUTH	NavUserPassword	Default auth mode
DEFAULT_USERNAME	admin	Default admin username
DEFAULT_IMAGE	mcr.microsoft.com/businesscentral:ltsc2022	Default Docker image
DEFAULT_ISOLATION	hyperv	Default container isolation mode

Installer Reference

.\install.ps1            # Install: npm install + build + register in Copilot CLI and VS Code
.\install.ps1 -Force     # Force reinstall: rebuilds TypeScript even if dist/ already exists
.\install.ps1 -Uninstall # Remove the bc-container entry from both MCP config files

The installer is safe to re-run at any time. It skips steps that are already complete unless -Force is passed. It never removes or overwrites other servers in the MCP config files. Docker Engine download uses parallel chunked downloads (8 streams) for fast installation.

License and Credits

MIT license. See LICENSE.

Jeffrey Bulanadi authored and maintains this project. Core Docker orchestration patterns originated in bc-docker-manager.

Built under learnbeyondbc, open-source Business Central tooling for the community.

Support this work: github.com/sponsors/learnbeyondbc