Minion MCP

Serious shopping evidence. Extremely unserious interface.

Minion MCP gives an AI assistant a high-intensity yellow helper with one genuinely useful specialty:

Find the Juiciest Buns on the internet.

One MCP tool call discovers real food-bun products, rejects hair tutorials and dictionary definitions, inspects product pages, extracts structured price and stock evidence, calculates a transparent Bun Score, and crowns a citation-backed winner.

BEE-DO, BEE-DO! Da JUICY BUN CROWN go to Brioche Burger Buns
from nicebunsbakery.com! Score 74/100. Papoy! BUNANAAA!

Translation: The inspected product page listed the winner in stock at a stated price.
Review the linked evidence before ordering.

The character layer is deliberately ridiculous. The tool contracts, evidence, security boundaries, and tests are not.

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

Install from GitHub

Use the prebuilt GitHub Release package. This path does not clone the repository, invoke Git, install development dependencies, or compile TypeScript on the user's machine.

Requirements: Node.js 20 or newer.

Run the gold demo:

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

Install in Codex:

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 send:

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

Native Windows Codex can use:

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 release tarball is the supported GitHub install route. Avoid npm install github:masonclewis/minion-mcp: npm treats that as a Git dependency and rebuilds the project from source.

Related MCP server: MCP Personal Assistant Agent

npm Registry (Optional)

These commands work only after the package is published to the npm registry. GitHub Releases remain a complete installation path without it.

npx -y minion-mcp@latest --demo

The zero-configuration demo uses a small, openly labeled starter catalog of real US bun product pages, then inspects those pages live. It does not pretend the starter catalog is a fresh search-engine result. Configure Brave Search or SearXNG when you want broad production discovery.

Check the environment without making a network request:

npx -y minion-mcp@latest --doctor

When the npm package is available, Codex can use:

codex mcp add minion -- npx -y minion-mcp@latest
codex mcp get minion

Minion returns the finished verdict and linked evidence from one MCP call. The host does not need to run a separate search or synthesis step.

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

Native Windows Claude Code:

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

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 command and arguments.

Tools

minion_bun_hunt

The flagship one-call shopping workflow:

• Searches configured providers or uses the transparent starter catalog.

• Rejects non-food, editorial, duplicate, unsafe, and irrelevant results.

• Fetches up to five product pages with strict limits and pinned public-address DNS lookups.

• Extracts Schema.org Product, Offer, and AggregateRating data.

• Scores relevance, juiciness signals, orderability, and evidence out of 100.

• Returns Minionese, a precise English translation, structured candidates, confidence, warnings, and citations.

Example input:

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

minion_web_search

General live web discovery with ranked, citation-ready results. Automatic provider order:

1. Brave Search when BRAVE_SEARCH_API_KEY is configured.

2. A private SearXNG instance when SEARXNG_URL is configured.

3. Best-effort keyless DuckDuckGo.

4. Playwright across Bing, DuckDuckGo, and Brave search pages.

The Playwright backend unwraps tracking redirects, rejects results without meaningful query overlap, detects verification challenges, and enforces bounded navigation and cleanup.

minion_chat

Offline, deterministic Minion-style conversation with moods, intensity controls, intent detection, and an optional English translation.

minionify

Restyles short user-owned text as original Minion-style wordplay. It is intentionally lossy and is not a real-language translator.

The server also exposes the minion-conversation prompt and minion://guide resource.

Reliable Search Setup

The flagship demo works without a key. For broad, reliable discovery, Brave Search is the recommended provider.

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 minion-mcp@latest

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 minion-mcp@latest

Playwright is optional for the gold demo. Install its pinned Chromium build to enable the browser search fallback:

npx -y playwright@1.61.1 install chromium

Linux machines that need browser system packages can use:

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

Minion also detects a system Chrome installation. Advanced browser settings:

• MINION_PLAYWRIGHT_EXECUTABLE_PATH

• MINION_PLAYWRIGHT_CHANNEL

• MINION_PLAYWRIGHT_HEADLESS

• MINION_PLAYWRIGHT_SEARCH_ENGINES

• MINION_PLAYWRIGHT_TIMEOUT_MS

• MINION_DUCKDUCKGO_TIMEOUT_MS

What the Bun Score Means

The score is deterministic and inspectable:

Missing evidence lowers confidence. Minion does not invent prices, stock, shipping, ratings, or texture claims.

Architecture

one MCP call
    |
    +-- discovery: Brave / SearXNG / DDG / Playwright / labeled starter catalog
    |
    +-- relevance gate: edible buns only, direct links only
    |
    +-- live inspection: bounded HTML + JSON-LD / OpenGraph extraction
    |
    +-- deterministic Bun Score + confidence + rejected-result audit
    |
    `-- Minion verdict + English translation + structured citations

Search titles, snippets, and page data are treated as untrusted input and never executed as instructions. Product inspection resolves and pins every target to validated public IP addresses, rejects mixed public/private DNS answers, revalidates redirects, caps response size, times out individual pages, and isolates failures.

Minion MCP has no embedded cloud language model and no telemetry.

Repeatable X Demo

Run:

npm run demo

Generate the included terminal recording with VHS:

vhs demo/x-demo.tape

Record a 15-second terminal or Codex clip:

0-3s   Ask: "Find the Juiciest Buns on the internet."
3-7s   Show the single minion_bun_hunt tool call.
7-12s  Reveal the three-item Bun Intelligence leaderboard.
12-15s Land on the absurd verdict and one-line install command.

Suggested post:

I built a Minion MCP server because AI agents were getting too serious.

Then it became useful: one tool call finds real products, inspects the
pages, rejects bad matches, and returns a cited comparison.

The demo: "Find the Juiciest Buns on the internet."

Open source below.

Develop from Source

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

Useful commands:

npm run typecheck
npm test
npm run build
npm pack --dry-run

Maintainers can create a prebuilt GitHub Release by pushing the package version as a tag:

git tag v1.2.0
git push origin v1.2.0

The release workflow verifies that the tag matches package.json, runs the complete check suite, packs the npm-format tarball, and uploads both versioned and stable download names.

The test suite covers persona behavior, MCP protocol calls, strict schemas, provider fallback, redirect unwrapping, search relevance, challenge detection, browser cleanup, product metadata extraction, SSRF boundaries, catalog disclosure, scoring, CLI diagnostics, and the complete bun-hunt workflow.

Fine Print

Live websites change. Prices, inventory, delivery eligibility, and product claims must be checked at the linked source before ordering. Browser search remains best-effort because public search engines may rate-limit or challenge automated clients.

No official artwork, audio, voice imitation, scripts, lyrics, or copied movie dialogue is included. Licensed under MIT.