@brutalist/mcp

Brutalist MCP

Multi-perspective code analysis using Claude Code, Codex, and Gemini CLI agents.

Get direct, honest technical feedback on your code, architecture, and ideas before they reach production.

What It Does

The Brutalist MCP connects your AI coding assistant to three different CLI agents (Claude, Codex, Gemini), each providing independent analysis. This gives you multiple perspectives on:

• Code quality and security vulnerabilities
• Architecture decisions and scalability
• Product ideas and technical feasibility
• Research methodology and design flaws

Real file-system access. Straightforward analysis. No sugar-coating.

Quick Start

Step 1: Install a CLI Agent

You need at least one of these installed:

# Option 1: Claude Code (recommended)
npm install -g claude

# Option 2: Codex
# Install from https://github.com/openai/codex-cli

# Option 3: Gemini
npm install -g @google/gemini-cli

Step 2: Install the MCP Server

Choose your IDE:

Claude Code:

claude mcp add brutalist --scope user -- npx -y @brutalist/mcp@latest

Codex:

# Install globally once to avoid npx startup chatter
npm i -g @brutalist/mcp
# Add MCP using the installed binary (clean stdio)
codex mcp add brutalist -- brutalist-mcp

Configuring tool_timeout_sec for Codex: The tool_timeout_sec parameter (defaulting to 60 seconds) for your Brutalist MCP server needs to be configured directly in your Codex configuration file at ~/.codex/config.toml. It cannot be passed via the codex mcp add command directly.

To set a custom timeout (e.g., 5 minutes or 300 seconds), add or modify the [mcp_servers.brutalist] section in ~/.codex/config.toml as follows:

[mcp_servers.brutalist]
command = "brutalist-mcp" # Ensure this matches your installation command
args = [] # Depending on your setup, this might be empty or contain arguments
tool_timeout_sec = 300 # Set your desired timeout in seconds

Cursor: Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brutalist": {
      "command": "npx",
      "args": ["-y", "@brutalist/mcp@latest"]
    }
  }
}

VS Code / Cline:

code --add-mcp '{"name":"brutalist","command":"npx","args":["-y","@brutalist/mcp@latest"]}'

Windsurf: Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brutalist": {
      "command": "npx",
      "args": ["-y", "@brutalist/mcp@latest"]
    }
  }
}

Step 3: Verify Installation

# Check which CLI agents are available
cli_agent_roster()

Usage Examples

Analyze Your Codebase

# Analyze entire project
roast_codebase "/path/to/your/project"

# Analyze specific modules
roast_codebase "/src/auth"
roast_codebase "/src/api/handlers"

Validate Ideas

# Evaluate a product concept
roast_idea "A social network for developers to share code snippets"

# Review technical decisions
roast_idea "Migrating our monolith to microservices with Kubernetes"

Review Architecture

# System architecture analysis
roast_architecture "Microservices with event sourcing and CQRS"

# Infrastructure design review
roast_architecture """
API Gateway → Load Balancer → 3 Node.js services → PostgreSQL
Redis for caching, Docker containers on AWS ECS
"""

Security Analysis

# Authentication review
roast_security "JWT tokens with user roles in localStorage"

# API security check
roast_security "GraphQL API with dynamic queries and no rate limiting"

Compare Perspectives

# Get multiple viewpoints on technical decisions
roast_cli_debate "Should we use TypeScript or Go for this API?"

# Compare architecture approaches
roast_cli_debate "Microservices vs Monolith for our e-commerce platform"

How It Works

This MCP server coordinates analysis from locally installed CLI agents:

• Claude Code CLI - Code review and architectural analysis
• Codex CLI - Security and technical implementation review
• Gemini CLI - System design and scalability analysis

Each agent runs locally with direct file-system access, providing independent perspectives on your code and design decisions.

Analysis time: Up to 25 minutes for complex projects. Thorough analysis requires time to examine code patterns, dependencies, and architectural decisions.

Pagination for Large Results

For analyses that exceed your IDE's token limit:

# Set chunk size for large codebases
roast_codebase({targetPath: "/monorepo", limit: 20000})

# Continue from where you left off
roast_codebase({targetPath: "/monorepo", offset: 20000, limit: 20000})

# Use cursor-based navigation
roast_codebase({targetPath: "/complex-system", cursor: "offset:25000"})

Features:

• Smart boundary detection (preserves paragraphs and sentences)
• Token estimation (~4 chars = 1 token)
• Progress indicators
• Configurable chunk size (1K to 100K characters)

Tools

Code & Architecture

Tool	Analyzes
roast_codebase	Security vulnerabilities, performance issues, code quality
roast_file_structure	Directory organization, naming conventions, structure
roast_dependencies	Version conflicts, security vulnerabilities, compatibility
roast_git_history	Commit quality, branching strategy, collaboration patterns
roast_test_coverage	Test coverage, quality gaps, testing strategy

Design & Planning

Tool	Analyzes
roast_idea	Feasibility, market fit, implementation challenges
roast_architecture	Scalability, cost, operational complexity
roast_research	Methodology, reproducibility, statistical validity
roast_security	Attack vectors, authentication, authorization
roast_product	UX, adoption barriers, user needs
roast_infrastructure	Reliability, scaling, operational overhead

Utilities

Tool	Purpose
roast_cli_debate	Multi-agent discussion from different perspectives
cli_agent_roster	Show available CLI agents on your system

Advanced Usage

Choose Specific CLI Agents

# Use a specific agent
roast_codebase(targetPath="/src", preferredCLI="claude")

# System automatically selects best agent for task
roast_security "/auth/module"  # Typically uses Codex

# Multi-agent analysis (default)
roast_idea "..."  # All available agents provide perspectives

Agent Strengths

Different agents have different strengths:

• Code review: Claude, Codex, Gemini
• Architecture: Gemini, Claude, Codex
• Security: Codex, Claude, Gemini
• Research: Claude, Gemini, Codex

Why Multiple Perspectives

Each CLI agent brings a different approach to analysis:

• Different training data and focus areas
• Independent evaluation of the same code
• Varied perspectives on technical tradeoffs

Getting multiple viewpoints helps identify issues that a single perspective might miss.

License: MIT Issues: https://github.com/ejmockler/brutalist-mcp/issues