ampl-mcp

An MCP server exposing AMPL optimisation modelling to coding agents, plus a matching Claude plugin.

Requirements

• An AMPL licence UUID (free community licences: https://ampl.com/ce) - optional, see below

• uv / uvx

Related MCP server: agent-skill-loader

Use

The AMPL solver wheels are served from https://pypi.ampl.com, not PyPI, so UV_INDEX must include it or resolution will fail outright. This applies to every uv/uvx invocation of this server.

Set your licence UUID in the environment (optional - see "Licensing" below):

setx AMPLKEY_UUID "your-uuid-here"     # Windows
export AMPLKEY_UUID=your-uuid-here     # POSIX

Then add the plugin, or run the server directly:

UV_INDEX=https://pypi.ampl.com uvx ampl-mcp

Not yet published to PyPI. Until it is, uvx ampl-mcp cannot resolve this package. Run it from a checkout instead:

UV_INDEX=https://pypi.ampl.com uvx --from . ampl-mcp

and point the plugin at the same thing by changing plugin/.mcp.json's args to ["--from", "/absolute/path/to/ampl-mcp", "ampl-mcp"].

Licensing

Without AMPLKEY_UUID the server still runs, on the wheel's shipped size-limited demo licence - small models solve correctly; a model past the demo's size limit fails with an error that reads like a modelling problem. Call the ampl_version tool to see which tier is active before assuming a failure is a modelling bug.

With AMPLKEY_UUID set, activation happens lazily on the first session and is persisted to a durable directory so it survives across runs: %LOCALAPPDATA%/ampl-mcp/licence on Windows, ~/.local/share/ampl-mcp/licence on POSIX (override with AMPL_MCP_LICENCE_DIR).

Development

UV_INDEX=https://pypi.ampl.com uv run pytest

Tests marked licence are skipped when no AMPL engine can be constructed (see tests/conftest.py) - AMPLKEY_UUID is not required, because the AMPL wheel ships a size-limited demo licence that is enough to build an engine. Set AMPL_MCP_REQUIRE_ENGINE=1 in CI to turn that skip into a hard failure.

Security note

The server blocks AMPL's shell and cd statements (in ampl_eval, ampl_sweep's collect expressions, and in files loaded by ampl_read_files) to prevent accidental shell/cd use. This is an accident-preventer, not a sandbox: it is not a guarantee that shell execution is impossible. Set AMPL_MCP_ALLOW_SHELL=1 if you need those statements.

Two things it deliberately does not stop:

• Loading a file runs that file's contents unchecked. include, commands, model, data and load are permitted on purpose - by project ruling, whoever approves the call owns what the loaded file does. The guard sees only the text handed to the server, so a shell inside a loaded file (or inside anything it loads in turn) will run. ampl_eval, ampl_read_files and ampl_display return a warnings list when they see such a statement; they do not refuse it.

• AMPL expression text is not confined to the working directory. The path guard applies to this server's own path arguments. AMPL's own output redirection - ampl_display("1 > 'C:/anywhere/file.txt'") - writes outside the session workdir, and an include with an absolute path reads from outside it.

Configuration