mcp-minion
A minimal ReAct agent that drives one or more MCP servers through an OpenAI-compatible API (OpenRouter by default). It reads a task from a run folder, loops "think → call tool → observe" until the model produces a final answer, and writes a complete JSON log of the run.
mcp-minion is developed in the mcp-solver
monorepo, where it is used to run solver templates over code-execution MCP
servers, but it has no dependency on the solver and works with any MCP server.
Install
From the monorepo (workspace member):
uv sync --package mcp-minion
Or standalone:
pip install -e minion
Set an OpenRouter API key, either in ~/.mcp-minion or in a run folder's .env:
OPENROUTER_API_KEY=sk-...
Run-folder config
A run folder holds everything for a single run:
| File | Required | Purpose |
|---|---|---|
config.json |
yes | Model, agent, MCP server, and kernel settings |
task.md |
yes | The specific task for this run |
project.md |
no | Shared instructions prepended to the task |
files.system target |
no | System-prompt body (see below) |
run_*.json |
auto | Per-run JSON log (written automatically) |
config.json (nested format):
{
"model": {
"name": "google/gemini-2.5-flash",
"temperature": 0,
"max_tokens": 2048
},
"agent": { "max_steps": 10, "max_total_tokens": 500000 },
"files": { "system": "system.md" },
"packages": ["z3-solver"],
"mcpServers": {
"ipython": { "command": "ipython_mcp", "args": [] }
}
}
Key options:
files.system— path (relative to the run folder) to a markdown file whose contents become the system prompt. If the file contains the literal placeholder{tool_sections}, the generated per-server tool list is spliced in at that spot (via a literal replace, so other{/}in the file — e.g. ASP templates — are left untouched); otherwise the tool list is appended after the file contents. Whenfiles.systemis absent, a built-in default system prompt is used.agent.max_total_tokens— hard cap on the cumulative input+output tokens of a single run. The cap is checked after each completed step: once the total exceeds it, the loop stops, the final answer becomes[Agent stopped: per-run token cap of N exceeded (cumulative M)], and the run log recordstoken_cap_reached(both on the last step and in the result). Omit the key — or set it to0— for no cap.max_stepsalone does not bound spending, since a single step can be arbitrarily expensive.mcpServers— the servers to start for the run. If any of them fails to start,mcp-minionaborts with aRuntimeErrornaming the server rather than running the agent with a silently reduced tool set.packages— packages to preinstall in a code-execution kernel. On the first call to apython_exectool, if nopython_resethas happened yet,mcp-minionautomatically callspython_resetwith these packages and reuses any returnedkernel_idfor subsequentpython_execcalls.
Examples
Bundled test server
The package ships a tiny MCP server exposing echo and add:
{
"model": { "name": "google/gemini-2.5-flash", "temperature": 0 },
"agent": { "max_steps": 5 },
"mcpServers": {
"test": {
"command": "python",
"args": ["-m", "mcp_minion.test_mcp_server"]
}
}
}
mcp-minion path/to/run_folder -v
IPython code execution
With an ipython_mcp server available:
{
"model": { "name": "google/gemini-2.5-flash", "temperature": 0 },
"agent": { "max_steps": 5 },
"mcpServers": {
"ipython": { "command": "ipython_mcp", "args": [] }
}
}
task.md:
Use the python_exec tool to compute sum(range(1, 11)) and report the result.
Artifacts
mcp_minion.artifacts.extract_last_submission(log_or_steps, tool_name="submit_code")
returns the code argument of the last successful call to a submission tool,
so callers can persist an agent's final code alongside the run log.
Tests
uv run --with-editable ./minion --with pytest --with pytest-asyncio \
python -m pytest minion/tests -q
The end-to-end tests under minion/e2e_tests/ make real API calls and are
skipped unless OPENROUTER_API_KEY is set.
Metadata
Release files for mcp-minion 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_minion-0.2.2.tar.gz | 36.7 kB | Without provenance | Details for mcp_minion-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_minion-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for mcp_minion-0.2.2-py3-none-any.whl |
Total release size: 63.1 kB
Release files / mcp_minion-0.2.2.tar.gz
| Download URL | mcp_minion-0.2.2.tar.gz |
|---|---|
| Size | 36.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b051b6f0ed62ffe99215257e7219ef96ef8f64e1f68813ddb3e8b1c6dd72e0f7
|
|
BLAKE2b-256 checksum How to use checksums |
dd3ab9e035647129c6dbe5644b92bbab73f500b3aa0d35e883acb83f880eb272
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / mcp_minion-0.2.2-py3-none-any.whl
| Download URL | mcp_minion-0.2.2-py3-none-any.whl |
|---|---|
| Size | 26.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c6674e4a49ed8859fbdabd250507513f0193e3be73a03c662ceb05dc34b7797e
|
|
BLAKE2b-256 checksum How to use checksums |
b790019f4039d8cdff585d71e26efa53d603bb41ef963b040bcf6463329f1398
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for mcp-minion 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.