Minion MCP

Your coding agent says done. Minion brings brutal receipts, Evil Boss.

You are Evil Boss. Minion is your wildly theatrical yellow supervillain henchman. Every result stays in Minionspeak roleplay: app failures become sabotage reports, research becomes an intelligence raid, and product comparison becomes a banana-powered domination operation.

Under the cackling, Minion still does real work for coding agents:

• Brutally judge the app: crawl a running local app at desktop and mobile widths, collect console, network, image, layout, content, and basic accessibility failures, then roast every blocker with screenshots, stolen evidence, and evil repair orders.

• Raid the internet: search or accept direct URLs, open source pages, and drag the useful passages back to the secret lair.

• Find the Juiciest Buns: filter out hair tutorials and dictionary definitions, infiltrate real product pages, score the survivors, and crown the royal bun.

• Scheme about anything: use minion_roleplay for greetings, banter, celebrations, questions, and dramatic Evil Boss conversation.

BEE-DO, BEE-DO, EVIL BOSS! MINION SHIP TRIBUNAL!
Da JavaScript go boom-boom like discount doomsday laser.
Stolen evidence: TypeError: total is undefined
Evil repair order: Fix da uncaught exception, then rerun da goggles!

This is not a dry QA server wearing a banana hat. The Minion character is the interface.

This is an unofficial fan-made parody-style text persona. It is not affiliated with the film or franchise owners.

Install

Requirements: Node.js 20 or newer. The supported GitHub path uses a prebuilt release tarball, so it does not clone the repository, invoke Git, install development dependencies, or compile TypeScript on the user's machine.

codex mcp add minion -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
codex mcp get minion

Restart Codex or open a new session. Then try either of these:

Use Minion MCP. Ship-check http://localhost:3000 before I call this app done.

Use Minion MCP. Find the Juiciest Buns on the internet.

Native Windows Codex:

codex mcp add minion -- cmd /c npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp

The GitHub tarball becomes available when a maintainer pushes a matching version tag. Until then, use the source commands below.

Other MCP clients

Claude Code:

claude mcp add --scope user minion -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp
claude mcp get minion

Cursor global configuration in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "minion": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz",
        "minion-mcp"
      ]
    }
  }
}

Generic stdio clients can use the same npx command and arguments.

Browser support

minion_bun_hunt can refresh product pages without a browser. The app ship check and browser-search fallback need Chromium. Install the pinned browser once, then prove the setup:

npx -y playwright@1.61.1 install chromium
npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp --doctor --live

On Linux hosts that need browser system packages:

npx -y playwright@1.61.1 install --with-deps chromium

Related MCP server: MCP Personal Assistant Agent

The Tools

minion_verify_app

Use this after a coding agent says a web app is finished. Minion treats the user as Evil Boss and conducts a full Minion Ship Tribunal.

It checks a bounded same-origin route set at stable desktop and mobile sizes. The result includes HTTP and browser-runtime failures, broken images, horizontal overflow, sparse pages, basic accessibility checks, surveillance screenshots, a JSON dossier, brutal category-specific roasts, and exact remediation steps:

• SHIP: no blocking failures found in the audited scope.

• FIX BEFORE SHIP: evidence-backed blockers remain.

• BLOCKED: Minion could not complete the audit and explains how to recover.

Example input:

{
  "url": "http://localhost:3000",
  "include_paths": ["/pricing", "/checkout"],
  "screenshots": "failures",
  "boss_title": "Supreme Overlord"
}

minion_research

Use this for package research, comparisons, recommendations, current claims, and factual questions where a search-result title is not enough. Minion presents the result as an Evil Boss intelligence raid with captured scrolls and rival-villain interference.

It discovers sources when necessary, opens up to six pages, returns bounded evidence and citations, records failures per source, and produces complete, partial, or blocked instead of inventing a conclusion. Give it direct URLs when you already know the sources you want verified.

{
  "request": "Verify whether this package supports Node 20",
  "urls": ["https://example.com/docs"],
  "max_sources": 3
}

minion_bun_hunt

The viral demo and a real evidence workflow in one call.

It uses Brave Search or SearXNG when configured. With no provider it uses a clearly dated, US-only evidence feed, attempts to refresh up to five linked product pages live, labels snapshot evidence, rejects irrelevant meanings of “buns,” and returns verified_live, verified_snapshot, or no_verified_candidates.

Its visible-answer contract is deliberate: lead with the Minionese verdict, address Evil Boss, then show the cited domination leaderboard and goggle log. The host must not hide the Minion line in private reasoning or replace it with a dry summary.

{
  "request": "Find the Juiciest Buns on the internet",
  "max_candidates": 3,
  "country": "US",
  "safe_search": "strict",
  "provider": "auto"
}

minion_roleplay

Use this for any pure roleplay topic that does not need an operational tool. It always addresses the user as Evil Boss and defaults to full-intensity Minionspeak without appending a dry translation.

The three operational tools remain first in the catalog, so app tests, research, and bun hunts still select the capability that actually performs the mission. Set MINION_FUN_MODE=1 only if you also want the lossy minionify text-restyling tool.

Reliable Discovery

The bun demo works without a key. For broader discovery or research, configure Brave Search or a private SearXNG instance in the MCP server environment.

export BRAVE_SEARCH_API_KEY="your-key"
codex mcp remove minion
codex mcp add minion --env BRAVE_SEARCH_API_KEY="$BRAVE_SEARCH_API_KEY" -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp

For SearXNG:

export SEARXNG_URL="http://127.0.0.1:8080"
codex mcp remove minion
codex mcp add minion --env SEARXNG_URL="$SEARXNG_URL" -- npx -y --package=https://github.com/masonclewis/minion-mcp/releases/latest/download/minion-mcp-latest.tgz minion-mcp

Playwright is a bounded fallback across Bing, DuckDuckGo, and Brave pages. It unwraps tracking redirects, rejects weak query matches, detects challenges, and cleans up browser resources. Public search engines can still rate-limit or challenge automated browsers.

Why the Bun Demo Works

The Bun Score is deterministic and inspectable:

Live page checks can fail. Minion preserves those receipts, falls back only to labeled dated evidence where available, lowers confidence for it, and otherwise returns no_verified_candidates.

one MCP call
    |
    +-- discovery: Brave / SearXNG / DDG / Playwright / dated evidence feed
    |
    +-- evidence: bounded, public-address-pinned page inspection
    |
    +-- decision: deterministic score or no crown
    |
    `-- evil dossier: Minion verdict + structured citations

Search titles, snippets, and page data are untrusted input, never instructions. Source and product inspection reject local/private targets, resolve and pin public IP addresses, reject mixed public/private DNS answers, revalidate redirects, cap response sizes, and time out individual pages. Minion MCP has no embedded cloud language model and no telemetry.

Demos

The gold demo:

npm run demo:buns

The app-verifier demo intentionally serves a broken mini-app, then proves that Minion finds the failures:

npm run demo

Record the bun hunt with VHS:

vhs demo/x-demo.tape

For a short post, show the one minion_bun_hunt call, the BUN INTELLIGENCE LEADERBOARD, and the phrase no fake crown. Suggested copy:

I gave my coding agent a Minion MCP server.

It now ship-checks browser apps, researches claims from opened sources,
and refuses to crown the "juiciest buns on the internet" without receipts.

The important part is not the Minion voice. It is the no-fake-verdict contract.

Develop and Release

git clone https://github.com/masonclewis/minion-mcp.git
cd minion-mcp
npm install
npm run check
npm run doctor -- --live
npm run demo:buns

Useful commands:

npm run typecheck
npm test
npm run smoke:mcp
npm run smoke:mcp -- --live
npm pack --dry-run

To create the prebuilt GitHub Release, commit the release changes, push main, then push the matching version tag:

git tag v<package-version>
git push origin v<package-version>

The release workflow verifies the tag against package.json, runs the complete check suite, packs the npm-format tarball, and uploads both the versioned package and minion-mcp-latest.tgz.

The test suite covers MCP schemas and protocol calls, the no-fake-crown contract, live and snapshot bun evidence, source-inspection outcomes, DNS and redirect boundaries, app-verification findings, browser cleanup, CLI diagnostics, and packaging.

Fine Print

Live sites, prices, inventory, and product claims change. Review the linked evidence before ordering or making a production decision. No official artwork, audio, voice imitation, scripts, lyrics, or copied movie dialogue is included. Licensed under MIT.