MiniZinc MCP Server

A Model Context Protocol (MCP) server that provides MiniZinc constraint programming capabilities.

Features

• Solve MiniZinc models using HiGHS solver (LP/MIP with float support)
• Validate MiniZinc models for syntax and type errors without solving
• Support for both MZN (model) and DZN (data) content as strings
• Automatic standard library inclusion (e.g., alldifferent.mzn) when not present in models
• Comprehensive output format: Parses DZN format for variable extraction, passthroughs output_text from explicit output statements
• JSON-RPC 2.0 protocol support via STDIO or HTTP transports
• Server-Sent Events (SSE) support for streaming responses

Quick Start

Prerequisites

• Elixir 1.18+
• MiniZinc installed and available in PATH

Note: MiniZinc is automatically installed in the Docker image.

Installation

git clone <repository-url>
cd minizinc-mcp
mix deps.get
mix compile

Usage

STDIO Transport (Default)

For local development:

mix mcp.server

Or using release:

./_build/prod/rel/minizinc_mcp/bin/minizinc_mcp start

HTTP Transport

For web deployments (e.g., Smithery):

PORT=8081 MIX_ENV=prod ./_build/prod/rel/minizinc_mcp/bin/minizinc_mcp start

Endpoints:

• POST / - JSON-RPC 2.0 MCP requests
• GET /sse - Server-Sent Events for streaming
• GET /health - Health check

Docker

docker build -t minizinc-mcp .
docker run -d -p 8081:8081 --name minizinc-mcp minizinc-mcp

Tools

The server provides the following MCP tools:

minizinc_solve

Solve a MiniZinc model using the HiGHS solver (LP/MIP with float support).

Parameters

• model_content (string, required): MiniZinc model content (.mzn) as string
• data_content (string, optional): DZN data content as string (e.g., "n = 8;"). Must be valid DZN format. Parsed and included in response as input_data field.
• timeout (integer, optional): Optional timeout in milliseconds (default: 30000, i.e., 30 seconds). Maximum allowed is 30000 ms (30 seconds); values exceeding this will be capped at 30 seconds.
• auto_include_stdlib (boolean, optional): Automatically include standard MiniZinc libraries (e.g., alldifferent.mzn) if not present (default: true)

The minizinc_solve tool returns solutions as JSON in the following format:

• DZN format parsing: When MiniZinc provides DZN format output (models without explicit output statements), variables are parsed and returned as structured data (e.g., {"x": 10, "y": [1, 2, 3]})
• Output text passthrough: When models include explicit output statements, the output text is passthrough'd in the output_text field (e.g., {"output_text": "x = 10\n"})
• Both formats: When both DZN and explicit output are available, both are included in the response
• Input data: When data_content is provided, the parsed DZN data is included in the input_data field
• Status: Solution status (e.g., "SATISFIED", "OPTIMAL_SOLUTION", "UNSATISFIABLE") is included when available

The response is always returned as a JSON string in the MCP content field.

The minizinc_solve tool automatically includes common MiniZinc standard libraries (e.g., alldifferent.mzn) if they are not already present in the model (when auto_include_stdlib is true). This means you can use standard functions like all_different without needing to add explicit include statements.

STDIO:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minizinc_solve",
    "arguments": {
      "model_content": "var int: x; constraint x > 0; solve satisfy;"
    }
  }
}

HTTP:

curl -X POST http://localhost:8081/ \
  -H "Content-Type: application/json" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "minizinc_solve", "arguments": {"model_content": "var int: x; constraint x > 0; solve satisfy;"}}}'

With data content:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minizinc_solve",
    "arguments": {
      "model_content": "var int: n; array[1..n] of var int: x; constraint all_different(x); solve satisfy;",
      "data_content": "n = 8;",
      "timeout": 30000
    }
  }
}

minizinc_validate

Validate a MiniZinc model by checking syntax and type checking without solving. Useful for debugging models before attempting to solve them.

Parameters

• model_content (string, required): MiniZinc model content (.mzn) as string
• data_content (string, optional): DZN data content as string (e.g., "n = 8;"). Must be valid DZN format.
• auto_include_stdlib (boolean, optional): Automatically include standard MiniZinc libraries (e.g., alldifferent.mzn) if not present (default: true)

Response Format

Returns a JSON object with:

• valid (boolean): Whether the model is valid
• errors (array): List of error messages (if any)
• warnings (array): List of warning messages (if any)
• message (string): Human-readable message (when valid)
• raw_output (string): Raw MiniZinc validation output (when invalid)

Validate a valid model:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minizinc_validate",
    "arguments": {
      "model_content": "var int: x; constraint x > 0; solve satisfy;"
    }
  }
}

Response for valid model:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "message": "Model is valid"
}

Validate a model with syntax errors:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minizinc_validate",
    "arguments": {
      "model_content": "var int: x; constraint x > 0 solve satisfy;"
    }
  }
}

Response for invalid model:

{
  "valid": false,
  "errors": [
    "Error: syntax error, unexpected solve, expecting ';'"
  ],
  "warnings": [],
  "raw_output": "..."
}

Configuration

Environment Variables:

• PORT - HTTP server port (default: 8081)
• HOST - HTTP server host (default: 0.0.0.0 if PORT set, else localhost)
• MIX_ENV - Environment (prod, dev, test)
• ELIXIR_ERL_OPTIONS - Erlang options (set to "+fnu" for UTF-8)
• MCP_SSE_ENABLED - Enable/disable Server-Sent Events (default: true, set to "false" to disable)

The server uses HTTP streaming only (no stdio transport).

Troubleshooting

MiniZinc not found: Ensure MiniZinc is installed and available in PATH. For Docker, MiniZinc is included in the image.

Port already in use: Change PORT environment variable or stop conflicting services.

Compilation errors: Run mix deps.get && mix clean && mix compile.

Debug mode: Use MIX_ENV=dev mix mcp.server for verbose logging.

Version

Current version: 1.0.0-dev2 (see mix.exs for latest version)

Requirements

• Elixir 1.18+
• Erlang/OTP 26+
• MiniZinc 2.9.3+ installed and available in PATH (or use Docker image which includes MiniZinc)

Building

mix deps.get
mix compile

Testing

mix test

Building Release

MIX_ENV=prod mix release

Running Locally

For STDIO transport (default):

mix mcp.server

PORT=8081 mix run --no-halt

License

MIT License - see LICENSE.md for details.

Copyright

Copyright (c) 2025-present K. S. Ernest (iFire) Lee