ampl-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ampl-mcp optimize a production schedule using AMPL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpThe 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 # POSIXRun the server directly
From a checkout, without installing the plugin:
uv run ampl-mcpThe 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 pytestTests 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,dataandloadare 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 ashellinside a loaded file (or inside anything it loads in turn) will run.ampl_eval,ampl_read_filesandampl_displayreturn awarningslist 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 anincludewith an absolute path reads from outside it.
Configuration
Variable | Purpose |
| AMPL licence UUID. Read from the environment only. |
| Must include |
| Override the durable licence directory. |
| Set to |
Available Tools
16 toolsampl_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
Scored across 16 tools
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.
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.
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.
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
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseBqualityDmaintenanceA Model Context Protocol server that enables Claude users to access specialized OpenAI agents (web search, file search, computer actions) and a multi-agent orchestrator through the MCP protocol.410-
- AlicenseAqualityBmaintenanceMCP server to dynamically load Claude Code skills into AI agents515MIT
- FlicenseNot gradedqualityBmaintenanceMCP server that bridges coding agents (Claude Code, Codex, Gemini CLI) via ACP for pair programming, enabling agents to consult each other as tools.3-
- AlicenseAqualityDmaintenanceMCP server that bridges OpenAI's Agents SDK with Claude Code, enabling web search, file search, and computer use capabilities directly in your development environment.29 npm1MIT