erbina

A Claude-Code-only MCP server that bootstraps your dev environment from one prompt — install, wire, and verify CLI tools and other MCP servers from curated recipes, and see where every MCP server lives across your scopes.

Named after the Lusitanian goddess of boundaries and crossings — erbina is the threshold a tool crosses to become part of your environment. Sibling to ataegina (goddess of rebirth), which is also erbina's proof-of-concept recipe #1.

The recipe contract is the core idea. One server, eleven tools, and a curated set of 500+ recipes spanning cli-tools, scope-wiring mcp-servers, and profiles that bundle them (see the Recipe gallery). Each is one YAML file held to a conformance bar — schema + linter policy + a 100%-covered offline suite, plus a weekly job that actually installs it on macOS, Linux, and Windows — and adding one is the point.

Why this exists

Setting up a coding-agent environment is death by a thousand cuts: you install a CLI, hand-edit a config, add an MCP server — then find out it's in the wrong scope and isn't showing up. Claude Code spreads MCP config across up to four files in two apps, with no single place that knows what's installed where (anthropics/claude-code#27458, #8288, #5963).

erbina makes setup a thing an agent does for you, and proves worked:

• It's an MCP server, so an agent must drive it. There is no human entry point — run it by hand and you get nothing. Nobody mistakes it for a manual installer that "should just work."
• Recipes, not one-shot installs. Each entry is a contract: detect → install → configure → verify. Idempotent by construction — it detects what's already there and skips it, and success means the tool runs, not that a line was written to a file. Recipes also compose (requires: prerequisites, profiles that bundle a whole set) and cover the full lifecycle: update → re-verify → rollback, uninstall, and a doctor health-check over everything erbina installed.
• Scope-aware. It knows about Claude Code's local / project / user scopes, wires MCP-server recipes into the right one, and audits all three so you finally have one place that answers "what's installed, and where?"
• Proven, not just written. On top of the offline suite, a weekly (and on-demand) CI job bootstraps recipes for real against live package managers on macOS, Linux, and Windows — so a renamed brew formula, a dead URL, or a bad winget id is caught, not shipped.

Install

erbina is a single Python file run by uv (it declares its own dependencies inline — no venv to manage).

git clone https://github.com/noahhyden/erbina
# register it with Claude Code (use --scope user to make it available everywhere)
claude mcp add erbina --scope user -- uv run --script /absolute/path/to/erbina/server.py

Then, in Claude Code, just ask: "use erbina to set up ataegina" — the agent inspects the recipe, shows you exactly what it will run, then bootstraps and verifies it.

Requirements: uv and Claude Code, on macOS, Linux, or Windows. Plus whatever a recipe's install method needs — typically brew on macOS, winget on Windows, or a language toolchain (cargo / go / pipx) or curl fallback elsewhere. Every method is guarded, so only one that actually exists on your machine ever runs.

Headless / CI usage

In an interactive session claude mcp add … (above) handles the trust prompt for you. A non-interactive claude -p run has no prompt to answer, so you load the server with --mcp-config and pre-approve erbina's tools with --allowedTools (their names are mcp__erbina__<tool>). Write an MCP config once:

// erbina.mcp.json
{ "mcpServers": { "erbina": {
  "command": "uv",
  "args": ["run", "--script", "/absolute/path/to/erbina/server.py"]
} } }

# read-only: discover + inspect (nothing executes)
claude -p "use erbina to list recipes, then inspect ripgrep" \
  --mcp-config erbina.mcp.json --strict-mcp-config \
  --allowedTools mcp__erbina__list_recipes mcp__erbina__inspect_recipe

# install for real (add mcp__erbina__bootstrap to the allowlist)
claude -p "use erbina to bootstrap the modern-unix profile" \
  --mcp-config erbina.mcp.json --strict-mcp-config \
  --allowedTools mcp__erbina__bootstrap

--strict-mcp-config makes the run use only the servers in that file, so it never picks up your global config. Omit --allowedTools and a headless call can't call any tool — that's the one thing new CI users trip on.

Tools

The server's instructions tell the agent to always inspect (or dry-run) and show you the commands before executing — erbina shells out to package managers with real privileges (it runs as a sibling process, not under Claude Code's Bash sandbox), so consent before execution is the safety model.

How a recipe works

A recipe is four phases an agent executes. The proof-of-concept entry, recipes/ataegina.yaml:

detect:   { command: "ataegina --version", expect_exit: 0 }   # skip install if present
install:                                                       # first guard to pass wins
  methods:
    - { id: homebrew, when: "command -v brew", run: "brew install noahhyden/tap/ataegina" }
    - { id: curl,     when: "command -v curl", run: "curl -fsSL .../install.sh | sh" }
configure: { steps: [ { run: "ataegina init --yes", needs_project_dir: true, optional: true } ] }
verify:   [ { command: "ataegina --version", expect_exit: 0 } ]

A kind: mcp-server recipe instead wires a server into a chosen scope — its configure step is claude mcp add <name> --scope ${scope} -- …, where ${scope} is substituted from the scope you pass to bootstrap. See recipes/fetch.yaml. A kind: profile recipe installs nothing itself — it just requires: a curated set, so one prompt bootstraps the whole bundle.

Recipes can also declare optional blocks: requires: (prerequisites bootstrapped first), version: + update: / rollback: (auto-updates, with latest: as a command or the { github: owner/repo } shorthand), and uninstall: (teardown). Because each install method's when: guard runs in the host shell, methods are cross-platform — a winget method fires only on Windows, brew/cargo/curl only where they apply. The full schema is in SCHEMA.md.