Docker deployment

PyMAPDL-MCP can be deployed as a containerized app using Docker with HTTP transport for remote access. The server can connect to either a containerized MAPDL instance or a local MAPDL installation.

Warning

HTTP transport is not encrypted. Use only in trusted networks or behind a reverse proxy (such as Nginx or HAProxy) that provides TLS/SSL.

Quick start with Docker Compose

The easiest way to run both MAPDL and the MCP server together is using Docker Compose.

1. Configure the environment:

   cp docker/env.example docker/.env
   

   Edit the docker/.env file with your settings:

   • PYMAPDL_IP: Set to mapdl (container), host.docker.internal (local Windows/Mac), or the IP address of a remote MAPDL instance.

   • ANSYSLMD_LICENSE_FILE: Your ANSYS license server (format: port@server).

2. Start services:

   docker compose -f docker/docker-compose.yml up
   

   Or run in detached mode:

   docker compose -f docker/docker-compose.yml up -d
   

   The MCP server is available at http://localhost:8080.

Docker Compose services

The docker-compose.yml file defines two services:

• pymapdl-mcp: The MCP server with HTTP transport enabled

• mapdl: An ANSYS MAPDL container (optional as you can connect to a local instance instead)

To connect to a local MAPDL instance instead of the container:

1. Remove or comment out the mapdl service and depends_on in the docker-compose.yml file.

2. Set PYMAPDL_IP=host.docker.internal (Windows/Mac) or the appropriate IP address.

3. Start MAPDL locally: pymapdl start --port 50052.

Build a standalone image

To build the MCP server image without Docker Compose, run from the repository root.

On Linux:

export GITHUB_TOKEN="your_token_here"
DOCKER_BUILDKIT=1 docker build --secret id=github_token,env=GITHUB_TOKEN \
  -f docker/Dockerfile -t pymapdl-mcp .

On Windows (PowerShell):

$env:GITHUB_TOKEN = "your_token_here"
$env:DOCKER_BUILDKIT = "1"
docker build --secret id=github_token,env=GITHUB_TOKEN `
  -f docker\Dockerfile -t pymapdl-mcp .

Run the standalone container

Connect to a local MAPDL instance:

# Windows/Mac
docker run -p 8080:8080 -e PYMAPDL_IP=host.docker.internal pymapdl-mcp

# Linux
docker run --network host -e PYMAPDL_IP=localhost pymapdl-mcp

Connect to a remote MAPDL instance:

docker run -p 8080:8080 \
  -e PYMAPDL_IP=192.168.1.100 \
  -e PYMAPDL_PORT=50053 \
  pymapdl-mcp

Environment variables

Variable	Default	Description
PYMAPDL_IP	host.docker.internal	MAPDL IP address or hostname
PYMAPDL_PORT	50052	MAPDL gRPC port
HTTP_HOST	0.0.0.0	HTTP server bind address
HTTP_PORT	8080	HTTP server port
ANSYSLMD_LICENSE_FILE	(required)	License server in port@server format

MCP client configuration

Once the container is running, configure your MCP client to connect to the HTTP server.

Visual Studio Code (.vscode/mcp.json):

{
  "servers": {
    "pymapdl": {
      "type": "http",
      "url": "http://localhost:8080"
    }
  }
}