Loadout MCP server

Loadout looks at your project and sets up Claude Code for it.

It works out which MCP servers, hooks, and skills fit your stack, shows you a short ranked list with a reason for each, and installs the ones you pick, writing the config for you. So you don't have to read a 500-item "awesome" list and copy-paste install commands by hand.

It also works with other agents: full setup for Claude Code, MCP servers plus lifecycle hooks for Codex, and MCP servers for Cursor, opencode, Gemini CLI, and OpenClaw. The bundled Loadout skills now ship with both Claude Code and Codex plugin manifests.

English · 한국어

---

TL;DR: point it at a repo, it recommends the Claude Code extensions that fit that repo, and applies the ones you pick.

The problem

The Claude Code ecosystem has thousands of skills, MCP servers, hooks, and plugins, spread across dozens of "awesome" lists. Those lists are good for discovery, but that's all they are: you read hundreds of entries, guess which ones apply to you, and copy-paste install commands one by one.

Loadout does the other half. Point it at a project and it tells you what to install for that project, then sets it up for you.

What it does

$ npx claude-loadout

🎯 Loadout  — gearing up Claude Code for this project

Detected: package.json, next, react, tailwind, prettier, playwright
Best-fit domains: Frontend / Web UI, General / Any project

Recommended loadout:

 1  Playwright (browser automation)  [MCP server]
     Drive a real browser — navigate, click, assert, screenshot — via accessibility snapshots.
     why: matches react, next, playwright

 2  Auto-format JS/TS on edit (Prettier)  [Hook/setting]
     After Claude edits a file, run Prettier on it so the diff is always clean.
     why: matches package.json, prettier, react

 3  Context7 (up-to-date docs)  [MCP server]
     Pulls version-accurate docs for thousands of libraries into context — kills hallucinated APIs.
     ...

Install which? numbers e.g. 1,3,4  ·  'a' = all  ·  Enter = skip: 1,2,3

✅ Applied:
  .mcp.json          + playwright, context7
  .claude/settings.json + format-js-on-edit

It scans your project (languages, frameworks, CI, existing config), matches it to one or more domains, and ranks a short loadout with a one-line reason for each item. You pick what you want and it writes the config, merging into .mcp.json and .claude/settings.json, never overwriting what's already there, and flagging any tokens you still need to fill in.

Two ways to use it

1. Inside Claude Code (recommended)

Add the marketplace once, then the recommender is a slash command:

/plugin marketplace add sukoji/loadout
/plugin install loadout@loadout

/loadout:recommend     # profile this repo, recommend a loadout, and apply what you pick
/loadout:browse        # just browse the catalog by domain, no changes

/loadout:recommend reads your repo the way a human would, then uses AskUserQuestion to let you check the items you want — and applies them in place.

2. As a standalone CLI

cd your-project
npx claude-loadout            # interactive
npx claude-loadout --dry-run  # just show the recommendation
npx claude-loadout --all      # apply the whole recommended loadout
npx claude-loadout doctor     # audit tokens, hook deps, security gaps
npx claude-loadout doctor --fix  # apply auto-writable suggestions (MCP + hooks)
npx claude-loadout export     # team loadout → .loadout.json
npx claude-loadout apply -f .loadout.json   # apply shared manifest
npx claude-loadout --help     # full flag list

Zero dependencies, ~1s for scan/recommend, nothing to install globally.

CLI flags

Flag	What it does
(none)	Interactive — pick items by number
--dry-run / -d	Show recommendations only; write nothing
--json	Print recommendations as JSON (no write; good for CI)
--all / -a / -y	Apply the top recommendations without prompting
--all --json	Apply top recommendations; print receipts as JSON only
--discover	Also surface unverified community skills
--target <id>	Write compatible config for cursor, codex, gemini, opencode, openclaw, or all (Codex gets MCP + hooks)
--list-targets	List agents and config file paths
export	Write team loadout manifest → .loadout.json (includes installed ids)
export --json	Print manifest JSON to stdout
apply -f <file>	Apply a shared team loadout
apply --ids id1,id2	Apply specific catalog ids (e.g. from doctor --json suggestions)
apply --suggestions	Apply top recommendations for this repo (no manifest file)
apply --suggestions --mcp-only	Suggestions: MCP servers only (skip skills/hooks)
apply --suggestions --limit N	Cap how many suggestions to apply (default 5)
apply -f <file> --target <id>	Apply manifest MCPs to Cursor, Codex, etc.
apply -f <file> --dry-run --json	Preview apply as JSON
apply -f <file> --json	Apply and print receipts as JSON
doctor	Audit: tokens, hook deps, cross-agent dupes, gaps
doctor --fix	Apply auto-writable suggestions (MCP + hooks) and print skill install steps
doctor --fix --mcp-only	Fix MCP servers only
doctor --fix --hooks-only	Fix hooks/settings only
apply --suggestions --hooks-only	Apply hook/setting suggestions only
doctor --fix --dry-run	Preview what --fix would apply
doctor --json	Audit JSON with domains, signals, suggestions, fixCommand*, applyCommand*, and summary (healthy / optionalOnly; exit 1 when fixes needed)
doctor --quiet	Warnings and fixes only (skip OK lines)
doctor --require-healthy	Exit 1 unless summary.healthy (optional plugins still count as healthy)
domains	List catalog domains, signal hints, and loadout sizes
domains <id>	Show one domain's loadout items
domains --json	Domains as JSON
show <id>	Show one catalog entry (config, install, homepage)
show <id> --json	Entry as JSON
search <query>	Search catalog by id, name, description, signals, domains
search <query> --type mcp|skill|hook	Limit search to one item type
search <query> --limit N	Cap results (default 20)
search <query> --json	Search results as JSON
stats	Catalog counts (domains, tiers, types)
stats --json	Stats as JSON
signals	Print detected project signals and matched domains
signals --json	Signals + domains as JSON (version, root, signals, domains, count)

Team loadouts: run export in a reference repo, commit .loadout.json, then teammates run apply -f .loadout.json (add --target cursor for non-Claude agents).

CI automation: profile a repo and apply gaps without prompts:

npx claude-loadout doctor --json > profile.json
# profile.json includes applyCommand / applyCommandMcpOnly / applyCommandIds
npx claude-loadout apply --suggestions --mcp-only --json

Copy-paste GitHub Actions job: examples/ci-doctor.yml.

Non-interactive shells (CI, pipes): use --dry-run, --json, --all, or --all --json — otherwise Loadout prints recommendations and exits without hanging on input.

What auto-applies vs what you do

Kind	Loadout writes it?	You still need to…
MCP servers	✅ merges into .mcp.json (or agent MCP file)	Fill API keys; OAuth on first use for hosted servers
Hooks & settings	✅ .claude/settings.json; Codex hooks use .codex/hooks.json	Install hook deps (jq, ruff, …); on Windows use Git Bash/WSL for shell hooks
Built-in skills (/init, /code-review)	❌ already in Claude Code	Run the slash command when you want it
Marketplace plugins (Exa, Superpowers, …)	❌ prints /plugin install …	Run those commands in Claude Code

Run npx claude-loadout doctor anytime to see unfilled placeholders and missing PATH tools.

Works with your agent — not just Claude Code

MCP servers are portable across today's agents; only the config file and format differ. Loadout writes the right one for each. Codex also receives compatible lifecycle hooks in .codex/hooks.json. Catalog skill install commands remain Claude-specific unless an entry explicitly says otherwise, while Loadout's own recommend and browse skills are packaged for both Claude Code and Codex.

npx claude-loadout --target codex        # writes .codex/config.toml + .codex/hooks.json
npx claude-loadout --target cursor        # writes .cursor/mcp.json
npx claude-loadout --target claude,cursor # apply to several at once
npx claude-loadout --target all           # every supported agent
npx claude-loadout --list-targets         # see them all

Target (--target)	Agent	Config file	MCP format
claude (default)	Claude Code	.mcp.json + .claude/settings.json	mcpServers + skills/hooks
cursor	Cursor	.cursor/mcp.json	mcpServers
gemini	Gemini CLI	.gemini/settings.json	mcpServers
opencode	opencode	opencode.json	mcp (type: local)
codex	Codex	.codex/config.toml + .codex/hooks.json	[mcp_servers.*] (stdio or HTTP) + lifecycle hooks
openclaw	OpenClaw	~/.openclaw/openclaw.json	mcp.servers

If you don't pass --target, Loadout targets Claude Code and points out any other agents it detects in the project.

Why this is different

Everyone else	Loadout
A flat list you read and filter yourself	Profiles your repo and recommends for it
"Here are 500 things"	"Here are the 6 things you need, and why"
Copy-paste install commands by hand	Writes .mcp.json / settings.json for you
Discovery only	Discovery + apply, in one step

It's also a plugin marketplace and a browsable catalog — so discovery, recommendation, and install all live in one place.

Coverage — three tiers (not just a fixed list)

Loadout pulls from three tiers, so it reaches the whole ecosystem without ever blindly applying something unvetted:

• Curated (38) — hand-verified MCP servers, hooks & skills. Safe to auto-apply; every npx package is checked to resolve on npm (npm run verify:mcp) and smoke-started in release checks (npm run test:mcps).
• Official marketplace (278) — Anthropic's official plugin directory, ingested automatically. Surfaced when they match your stack, installed via /plugin.
• Community (--discover) — well-known community skills like caveman (token saver). Shown only when you ask, labeled ⚠ unverified, and never auto-applied.

npx claude-loadout            # curated + matching official plugins
npx claude-loadout --discover # also surface community skills (review before installing)

Domains

Loadout organizes its curated catalog by the kind of project you're working on:

Domain	For
Frontend / Web UI	React, Vue, Svelte, Next — anything in a browser
Backend / API	Servers, APIs, databases
Data / ML / Notebooks	Python data work, training, analysis
Research / Academic	Literature review, notebooks, papers, experiments
DevOps / Infra	CI/CD, Docker, Terraform, Kubernetes
Mobile	iOS, Android, React Native, Flutter
Game Development	Godot, Unity, Unreal
Security-sensitive	Auth, payments, PII
Docs / Writing / Office	Docs and real Word/Excel/PDF/PPT deliverables
General / Any project	The always-useful baseline

Full browsable index: docs/domains/.

How it works

your repo ──▶ scan (signals) ──▶ match domains ──▶ rank loadout ──▶ you pick ──▶ apply
             package.json,        frontend +        by signal        multi-      .mcp.json
             requirements.txt,    general           strength         select      .claude/settings.json
             Dockerfile, .env…                                                    + install commands

• Catalog (plugins/loadout/catalog/*.json) is the single source of truth — MCP servers, skills, and hooks, each tagged with the domains and signals it fits. Both the skill and the CLI read the same data.
• Recommender scores every domain by how many of its signals appear in your project, unions the top domains' loadouts, drops anything you already have, and ranks the rest.
• Apply deep-merges into your config. Hooks append to the right event arrays; MCP servers land under mcpServers; skills print the exact /plugin or built-in commands to run.

Contributing a catalog entry

The catalog is meant to grow with the community. Add an entry to the relevant file in plugins/loadout/catalog/, tag it with domains and signals, run the checks, and open a PR:

npm run validate     # catalog integrity: unique ids, required fields, domain references
npm run build:docs   # regenerate docs/domains/ from the catalog

See CONTRIBUTING.md for the entry schema.

Roadmap

Done (0.3.x)

• Publish claude-loadout to npm for npx
• loadout doctor / doctor --fix — audit and auto-apply MCP + hooks
• Team loadouts — export / apply -f .loadout.json, --ids, --suggestions
• Cross-agent targets — Cursor, Codex, Gemini, opencode, OpenClaw
• Catalog browse — domains, show, search, stats
• Research + game-dev domains; signal-gated recommendations

Next

• Runtime-verified curated catalog growth (research MCPs only after npm run test:mcps)
• Optional CI publish via repo NPM_TOKEN secret (workflow already ships)

Later

• More domains (embedded, browser extensions, Rust systems)
• Demo GIF / directory submissions (awesome-claude-code, marketplaces)

License

MIT © sukoji. The catalog links to third-party tools owned by their respective authors; Loadout only curates and configures them.

Privacy · Terms · Support