🪨 grug-brain-mcp

An MCP server that channels the wisdom of The Grug Brained Developer into your Claude Code workflow.

complexity very, very bad.

Quick Start (Claude Code)

Add for all your projects (user scope):

claude mcp add grug-brain --scope user -- npx -y grug-brain-mcp

Add for current project only (default/local scope):

claude mcp add grug-brain -- npx -y grug-brain-mcp

Share with your team — add a .mcp.json at your project root:

{
  "mcpServers": {
    "grug-brain": {
      "command": "npx",
      "args": ["-y", "grug-brain-mcp"]
    }
  }
}

Verify it's connected:

/mcp

You should see grug-brain: connected.

Tools

Once connected, Claude Code will automatically use these when relevant — or you can ask for them directly:

| Tool | What it does | Example prompt | |------|-------------|----------------| | grug_review | Reviews code/architecture for complexity demons | "use grug_review on this service class" | | grug_advice | Grug's take on any software decision | "ask grug if we should use GraphQL" | | grug_say_no | Makes the case against a proposed feature/abstraction | "grug_say_no to adding a plugin system" |

Also exposes a grug://principles resource (all 20 core principles) and a complexity-check prompt template.

Usage Examples

🔍 Code Review — find the complexity demons

> Use grug_review on src/services/UserService.ts

Grug will point out things like: too many dependencies, over-abstracted class hierarchies, unnecessary generics, and suggest simpler alternatives.

> grug_review this auth middleware — is it too clever?

> Review our database layer with grug_review, focus on the ORM abstractions

🧠 Architecture Advice — ask grug before you regret

> Ask grug: should we split our monolith into microservices?

grug wonder why big brain take hardest problem, factoring system correctly, and introduce network call too

> grug_advice: we're debating between GraphQL and REST for our new API

> Ask grug: team wants to add Redis caching layer, worth the complexity?

> grug_advice: should we adopt Kubernetes for our 3-person startup?

🚫 Say No — let grug fight the feature creep

> PM wants real-time collaborative editing. Use grug_say_no.

Grug will either argue for "no" or propose an 80/20 compromise that delivers most of the value with a fraction of the complexity.

> grug_say_no to adding a plugin system with hot-reloading

> Architect wants to introduce event sourcing. grug_say_no, who_wants_it: "senior architect"

> grug_say_no to rewriting our working jQuery frontend in React

📋 Complexity Audit — quick health check

> Do a complexity-check on src/auth/middleware.ts

Returns a complexity demon rating from 1-5 clubs (🪨) and the top 3 things grug would simplify.

💡 Combine with your workflow

> Review the last PR diff from a grug perspective

> I'm about to refactor the payment module. Ask grug for advice first.

> We have 47 microservices. Ask grug what he thinks.

> grug_review the Dockerfile — is it overengineered?

Also works with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "grug-brain": {
      "command": "npx",
      "args": ["-y", "grug-brain-mcp"]
    }
  }
}

Grug's Core Philosophy (TL;DR)

All 20 principles from grugbrain.dev are baked in. The big ones:

• Complexity very, very bad — the eternal enemy
• Say "no" — best weapon against complexity demon
• Say "ok" with 80/20 — when compromise necessary, deliver 80% value with 20% code
• Don't abstract too early — let cut-points emerge naturally
• Integration tests are the sweet spot (not unit, not e2e)
• Locality of behavior > separation of concerns — put code on the thing that does the thing
• Chesterton's fence — understand before you destroy
• Microservices? — why take hardest problem and add network call too?
• Logging — always more logging
• FOLD — Fear Of Looking Dumb is complexity demon's greatest ally

How it works

The tools return structured prompts infused with grug philosophy. Claude then responds in grug voice, applying the principles from grugbrain.dev to your specific situation.

The server itself is ~100 lines of code. grug approve of this.

License

MIT

Credits

All grug wisdom from grugbrain.dev by Carson Gross, creator of htmx.

grug just package it up so complexity demon easier to fight.