Skip to main content

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. When files.system is 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 records token_cap_reached (both on the last step and in the result). Omit the key — or set it to 0 — for no cap. max_steps alone 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-minion aborts with a RuntimeError naming 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 a python_exec tool, if no python_reset has happened yet, mcp-minion automatically calls python_reset with these packages and reuses any returned kernel_id for subsequent python_exec calls.

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)

Source distribution for mcp-minion 0.2.2
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)

Table of built distributions (wheels) for mcp-minion 0.2.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page