Skip to main content
Glama

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

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.

Available Tools

16 tools
ampl_close_sessionB

Dispose the engine, removing the workdir if the server created it.

Inputs: name. Returns: object

ampl_diagnoseA

Explain the last solve: status, message, and violated constraints.

Call this after an infeasible or unbounded result rather than guessing at the model.

Inputs: session. Returns: object

ampl_displayA

Evaluate an arbitrary AMPL display expression. The reach-anything tool.

A warnings list appears on the result when expr carries a file-loading statement (include, commands, model, data, load). Loading is permitted on purpose, but the loaded file's contents are executed WITHOUT being guard-checked.

This tool evaluates AMPL, so AMPL's own output redirection (display 1 > 'somewhere.txt';) applies and is NOT confined to the session working directory. The path guard covers this server's own path ARGUMENTS, not AMPL expression text.

Inputs: expr (required), limit, session. Returns: object

ampl_evalA

Run AMPL statements in order, returning per-statement output and errors.

Model-mode set literals need braces: set S = {1,2,3}; and set S := {1,2,3}; both work. Omitting the braces, e.g. set S := 1 2 3;, is a syntax error in model mode. A failing statement stops the batch but never kills the session.

statements must be a non-empty list of strings that contains at least one actual statement: an empty list, or input that is only comments and whitespace, is reported as an argument_error rather than as a successful call over nothing.

A warnings list appears on the result when a statement loads a file (include, commands, model, data) or a shared library (load). Loading is permitted on purpose, but the loaded file's contents are executed WITHOUT being guard-checked - read the warning and tell the user rather than assuming the guard covered it.

Inputs: statements (required), session. Returns: object

ampl_get_dataA

Read an entity's values as records.

suffix selects val, dual, rc, slack, lb or ub, so this one tool covers primal values, duals, reduced costs and bounds. At most one suffix may be requested per call: results.entity_rows tells an indexed (index, value) pair apart from a scalar value by checking for a 2-tuple, so passing multiple suffixes to get_values() on a scalar entity would be silently misread as an index/value pair.

Reading a PARAMETER can have a side effect: an indexed default that has never been referenced is computed and cached by AMPL only when read (documented AMPL laziness, not an amplpy quirk), and this tool forces that computation, but ONLY when a plain read comes back empty or short - never unconditionally - so a data-dependent default already read here keeps the value it had when read rather than tracking later changes to what it depends on; avoid reading such a parameter until you are done changing the data it depends on. If some instances of a PARAMETER (or VARIABLE) still have no value afterwards (a parameter with no default that was only partially assigned), that is reported via notes with ok: false, never silently reported as a complete, successful read. This completeness check does not apply to sets, constraints or objectives: num_instances() counts something other than "rows returned" for those (e.g. 1 for a whole set regardless of how many members it has), so comparing the two would misreport a perfectly normal empty set as a failed read.

name must be a bare AMPL entity name; it is interpolated into an AMPL statement, so anything else is an argument_error. limit is the page size and must be at least 1 - a limit of 0 or less is an argument_error, not an empty page reported as a successful read.

Inputs: name (required), limit, offset, suffix, +2 more. Returns: object

ampl_init_sessionA

Start an AMPL engine. No engine exists until this is called.

workdir defaults to a per-session temporary directory; pass a path to work against a real project. Every path ARGUMENT to a tool is resolved inside it and an escape is refused - but this is not a sandbox: AMPL expression text is not path-guarded (ampl_display("1 > 'C:/elsewhere.txt'") writes outside it via AMPL's own redirection), and an include with an absolute path reads from outside it.

Inputs: name, solver, workdir. Returns: object

ampl_list_entitiesA

List declared entities with their shape. The map of what has been built.

Call this when unsure what exists rather than guessing at names.

Inputs: kind, session. Returns: object

ampl_list_sessionsA

List live sessions and which one is current.

Inputs: no named parameters. Returns: object

ampl_optionA

Get an AMPL option, or set it when value is given.

An option name AMPL does not have is an argument_error, on both the get and the set: AMPL creates an option on first assignment, so a typo like ampl_option("solvre", "cbc") would otherwise report success while creating an inert option and leaving the real solver untouched. The one exception is the <solver>_options directive convention (highs_options, gurobi_options, ...), which by design does not exist until you create it.

value must be a string when given.

Inputs: name (required), value, session. Returns: object

ampl_read_filesA

Load .mod/.dat/.run files by path, resolved inside the session workdir.

Each file's contents are guard-checked exactly like a statement passed to ampl_eval before AMPL is asked to load it: a shell statement hidden inside a .run/.mod/.dat file is refused, not silently executed, subject to the same AMPL_MCP_ALLOW_SHELL escape hatch.

That check stops at the file it is given. If the file itself loads another file (include, commands, model, data) or a shared library (load), AMPL executes THAT file's contents unchecked - a shell there will run. Such statements are permitted deliberately and reported in a top-level warnings list; read it and tell the user.

On a load failure, message is a human-readable string and the full per-statement record is under detail.

Inputs: run, data, model, session. Returns: object

ampl_restart_sessionB

Restart the engine, discarding all model state. The recovery path.

Inputs: name. Returns: object

ampl_set_dataA

Assign a parameter from JSON, avoiding hand-written .dat syntax.

values may be a scalar, a mapping of index to value, or a list of [index..., value] records for multi-dimensional entities. The parameter must already be declared. This tool handles parameters only; to declare or assign a set, use ampl_eval with a statement such as set S = {1,2,3};.

name must be a bare AMPL entity name; it is interpolated into an AMPL statement, so anything else is an argument_error.

Inputs: name (required), values (required), session. Returns: object

ampl_solveA

Solve the current model and summarise the outcome.

Returns a bounded tail of solver output, not the whole log. Read duals and reduced costs afterwards with ampl_get_data(name, suffix="dual"|"rc").

ok is only true when solve_result is exactly "solved", no error or warning was captured, no output-stream failure marker was seen, AND at least one objective was declared: AMPL happily reports solve_result "solved" for a session with no model at all, or for a model with no objective, even though no solver was ever reached.

Inputs: solver, options, session, log_tail, +1 more. Returns: object

ampl_sweepA

Set a scalar parameter to each value, re-solve, and collect results.

Server-side so a twenty-point study is one call rather than forty round trips; AMPL re-presolves only what changed. Each run goes through the same shared core as ampl_solve (_solve_once), so it gets the same output-failure-marker scan, the same "solved AND has an objective" requirement for ok, and the same stable objective_name/objective_value shape - not a re-implementation that would silently reopen the holes Task 8 closed. objective, if given, is activated with an objective <name>; statement before the first solve (exactly like ampl_solve's own objective=) so every run actually optimizes that objective, not merely reports its value computed at some other objective's optimum; a bogus name is caught before any solve runs, the same way ampl_solve catches it. Omit objective to use whichever objective AMPL reports first, which on a model with more than one declared objective may not be the one actually active.

A value that fails to assign (wrong parameter name, wrong type, a value outside a declared domain) is recorded as its own failed run (ok False, with a message) and the sweep continues through the remaining values rather than aborting. collect names extra AMPL expressions evaluated with ampl.get_value after each solve; each is guard-checked exactly like a statement passed to ampl_eval, so collect cannot become another route to shell, and none may reuse a name this tool already uses for a run's own fields (value, ok, solve_result, ...) - doing so would silently overwrite that field instead of adding a new one. The overall ok is false if any run failed.

The parameter is left at whatever the LAST swept value was; this tool never restores the value it had before the call. A later ampl_solve() on the same session solves against that last value, not the model's original state - re-set the parameter first (e.g. via ampl_set_data) if that is not what is wanted.

Inputs: param (required), values (required), solver, collect, +3 more. Returns: object

ampl_use_sessionC

Make name the current session.

Inputs: name (required). Returns: object

ampl_versionA

Report server build, AMPL versions, licence tier and installed solvers.

Requires no session. Call this first when anything is unexplained: a demo licence solves small models happily and fails only on larger ones, with an error that reads like a modelling problem.

amplpy_version is always reported. ampl_version is the AMPL engine's own version banner, which only a live engine can be asked for: it is None when no session is running (the key is still present, so the result shape does not change depending on whether a session happens to exist). Call ampl_init_session first if you need it.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of the AMPL workflow: session lifecycle, code execution, data I/O, solving, options, and diagnostics. Even overlapping tools like eval/display/read_files are clearly separated by input type and purpose.

    Naming Consistency4/5

    All tools share the ampl_ prefix, and most follow a verb_noun pattern (list_sessions, init_session, set_data). A few bare verbs (eval, solve, display) and nouns (version, option) deviate, but the prefix and common AMPL vocabulary keep names predictable.

    Tool Count4/5

    At 16 tools, this is slightly above the typical 3-15 range, but the complete AMPL lifecycle justifies each tool without redundancy. The count feels appropriate for a comprehensive modeling server.

    Completeness5/5

    The toolset covers session management, model building (eval/read_files), data manipulation (set/get), solving (solve/sweep), options, and diagnostics. No obvious missing operations for the domain.

    Related MCP Connectors

    Related MCP Servers