claude-setup-audit-mcp

An MCP server that tells you why Claude Code keeps ignoring your instructions, then helps you fix it.

Three tools:

audit_claude_setup scores a repo's Claude Code setup from 0 to 100 and lists what to fix in order. It checks whether CLAUDE.md exists, whether it lists commands and do-not rules, whether it is short enough to be read, whether it leaks a credential, whether your subagents have proper frontmatter and restricted tools, whether you have skills, hooks, and an .mcp.json, and whether settings.local.json is git-ignored.

scaffold_agent writes a complete .claude/agents/<name>.md from a one-line job description, with frontmatter, a procedure, a report format, and do-not rules.

hook_recipes returns three settings.json hooks that work on Windows and macOS: a formatter after every edit, a guard that blocks destructive shell commands, and a bell when Claude stops and is waiting on you.

Install

Add to .mcp.json in your repo (or to Claude Code with claude mcp add):

{
  "mcpServers": {
    "claude-setup-audit": {
      "command": "npx",
      "args": ["-y", "claude-setup-audit-mcp"]
    }
  }
}

On Windows, use "command": "cmd", "args": ["/c", "npx", "-y", "claude-setup-audit-mcp"].

Then in Claude Code: "audit this repo's Claude setup". It calls the tool and reads you the findings.

Run from source

npm install
npm run build
npm run smoke   # audits ../claude-code-starter-pack and checks all three tools

No network calls, no telemetry. It reads files under the path you give it and nothing else.

What the score means

Under 40: Claude is working from nothing. Start with CLAUDE.md and the commands section. 40 to 70: the basics exist but nothing is enforced. Add hooks and restrict agent tools. Over 70: the setup is sound. The remaining gains come from agents written for your specific repeated jobs, which is what I do for teams. Details at github.com/shadrach16.

A ready-made starting point is the claude-code-starter-pack.

MIT licensed. Built by Tunde Oluwamo.