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

Install as a Claude Code plugin

This repository is its own plugin marketplace, so both steps take the repo URL:

/plugin marketplace add worc4021/ampl-mcp
/plugin install ampl@ampl-mcp

The plugin runs the server straight from its own checkout (uv run --directory ${CLAUDE_PLUGIN_ROOT} ampl-mcp), so nothing needs to be published to PyPI and no UV_INDEX has to be set - the AMPL package index is declared in pyproject.toml.

Set your licence UUID first if you have one - it is optional, see "Licensing":

setx AMPLKEY_UUID "your-uuid-here"     # Windows, then open a new terminal
export AMPLKEY_UUID=your-uuid-here     # POSIX

Run the server directly

From a checkout, without installing the plugin:

uv run ampl-mcp

The package is not on PyPI, so uvx ampl-mcp will not resolve it. Use uvx --from . ampl-mcp from a checkout if you want the uvx form.

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

Variable	Purpose
AMPLKEY_UUID	AMPL licence UUID. Read from the environment only.
UV_INDEX	Must include https://pypi.ampl.com.
AMPL_MCP_LICENCE_DIR	Override the durable licence directory.
AMPL_MCP_ALLOW_SHELL	Set to 1 to permit AMPL's shell and cd.