MCP

Advanced Claude Code Setup for macOS

Master Claude Code with 500+ MCP servers, advanced configurations, and hidden features that power users leverage for 150-300% productivity gains. Solo developers report completing 3-week tasks in 45 minutes. This comprehensive guide covers everything from installation to production workflows used by developers shipping real products.

Official GitHub Official Documentation Discord Community

Installation & Setup Quick Start Guide Solo Developer Workflows Essential MCP Servers CLAUDE.md Configuration Advanced Automations Hooks System Real-World Case Studies Hidden Features Workflow Optimization Project Lifecycle macOS Integration Troubleshooting

Installation & Setup

Prerequisites

Node.js 18.0 or higher
npm or yarn package manager
Anthropic API key from console.anthropic.com
macOS 12.0+ (for macOS-specific features)

# Install Claude Code CLI globally
npm install -g @anthropic/claude-code

# Verify installation
claude --version

# Set up your API key (required for first use)
export ANTHROPIC_API_KEY="sk-ant-..."

# Add to ~/.zshrc or ~/.bash_profile for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc

# Initialize Claude Code in your project
claude init

API Key Security

Never commit your API key to version control. Use environment variables or the secure config command:claude config set api_key

Quick Start Guide

Get started with Claude Code in minutes. These commands cover the most common use cases:

# Start an interactive session
claude

# Ask a specific question
claude "explain the architecture of this React app"

# Resume previous session
claude --resume

# Use specific model (claude-3-opus, claude-3-sonnet, claude-3-haiku)
claude --model claude-3-opus "refactor this code"

# Enable extended thinking for complex tasks
claude --think "design a scalable microservices architecture"

# Run in headless mode for automation
echo "analyze security vulnerabilities" | claude -p

# Use with specific directory context
claude --dir ./src "update all components to use TypeScript"

# Generate code with specific requirements
claude --generate "create a REST API with authentication"

Pro Tips

• Use Tab for command completion
• Type /help in interactive mode for commands
• Check ~/.claude/logs/ for debugging
• Use --dry-run to preview changes

Common Workflows

• Code review: git diff | claude -p
• Debug errors: claude "fix this error: [paste]"
• Refactor: claude --think "refactor for performance"
• Document: claude "add JSDoc comments"

Solo Developer Productivity Workflows

Solo developers using Claude Code achieve documented productivity gains of 150-300%, with some reporting the ability to complete previously 3-week tasks in just 45 minutes. The key is treating Claude Code as a persistent development partner through strategic configuration and workflow automation.

📊 Productivity Metrics

Development velocity:+150-300%
Bug resolution time:-60%
Configuration errors:-91%
PR rejection rate:-65%
Code generation accuracy:+78%

⚡ Multi-Instance Strategy

Run 3-5 Claude instances simultaneously for maximum productivity:

# Terminal 1: Frontend
cd ~/project/frontend && claude

# Terminal 2: Backend
cd ~/project/backend && claude

# Terminal 3: Testing
cd ~/project && claude --mode test

Daily Workflow Routine

# Morning Planning (15 minutes)
# 1. Review yesterday's work
claude-code review-commits --since yesterday --format summary

# 2. Plan today's work  
claude-code plan --from-tickets "PROJ-123, PROJ-124" --estimate-effort

# 3. Identify blockers
claude-code analyze-risk "Implement payment gateway integration"

# Session Management Best Practices
- Use --dangerously-skip-permissions for trusted environments
- Clear context between major tasks with /clear
- Maximum 2-3 hour sessions before resetting
- Separate terminals for different concerns

💰 Cost Analysis

Light Usage

$20-50/month

~1000 messages

Heavy Usage

$100-200/month

~5000 messages

ROI

10-100x

Based on time savings

Essential MCP Servers for Web Development

Desktop Commander MCP

Verified

Most powerful macOS system integration with terminal commands, process control, and file operations

GitHub npm

npx @wonderwhy-er/desktop-commander@latest setup

In-memory code executionSurgical text replacementsReal-time process management

Filesystem MCP

Verified

Official Anthropic filesystem server for sandboxed file operations

GitHub npm

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects

Sandboxed accessDirectory allowlistingSafe file operations

Git MCP Server

Verified

Official Git integration for repository operations

GitHub npm

claude mcp add git -s user -- npx -y @modelcontextprotocol/server-git --repository ~/Projects/my-app

Commit managementBranch operationsDiff generation

GitHub MCP

Verified

GitHub API integration for repository and issue management

GitHub npm

claude mcp add github -s user -- npx -y @modelcontextprotocol/server-github

PR automationIssue trackingActions integration

PostgreSQL MCP

Verified

Natural language PostgreSQL database operations

GitHub npm

claude mcp add postgres -s user -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

Query builderSchema managementMigration tools

Master CLAUDE.md Configuration

CLAUDE.md files serve as your project's constitution with hierarchical loading that prioritizes local configurations. The most effective configurations follow a 150-250 line sweet spot that balances comprehensive context with token efficiency. Claude reads these files in order:

./CLAUDE.md - Project root configuration
./CLAUDE.local.md - Personal preferences (gitignored)
~/.claude/CLAUDE.md - Global settings
Parent and child directories for context inheritance

📁 Hierarchical Configuration Strategy

For complex projects, use multiple CLAUDE.md files for better context management:

project-root/
├── CLAUDE.md                 # Project overview (150 lines)
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md        # React-specific patterns (100 lines)
│   ├── backend/
│   │   └── CLAUDE.md        # API conventions (100 lines)
│   └── shared/
│       └── CLAUDE.md        # Shared type definitions (50 lines)

✅ Result: 91% reduction in configuration errors, 78% increase in code generation accuracy

Basic CLAUDE.md Example

# Project Context

This is a Next.js 14 application using TypeScript and Tailwind CSS.

## Tech Stack
- **Frontend**: React 18, TypeScript 5.2, Next.js 14
- **Styling**: Tailwind CSS, shadcn/ui
- **Backend**: Node.js, Express, PostgreSQL
- **Testing**: Jest, React Testing Library, Playwright

## Development Commands
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run test` - Run test suite
- `npm run lint` - Run ESLint
- `npm run type-check` - Run TypeScript compiler

## Code Style Guidelines
- Use functional components with hooks
- Prefer TypeScript strict mode
- Follow Airbnb style guide
- 2-space indentation
- camelCase for variables, PascalCase for components

## Project Structure
- `/src/app` - Next.js app router pages
- `/src/components` - Reusable React components
- `/src/lib` - Utility functions and helpers
- `/src/types` - TypeScript type definitions

## Workflow Requirements
- Always run type-checking after code changes
- Use conventional commit messages (feat:, fix:, docs:, etc.)
- Create feature branches, never commit to main
- Run tests before suggesting any changes
- Update relevant documentation when changing APIs

## Important Notes
- Never modify files in /dist or /build directories
- Do not commit node_modules or .env files
- Use pnpm instead of npm for package management
- Always handle errors with proper try-catch blocks
- Add JSDoc comments for public APIs

Advanced CLAUDE.md with Imports

# Advanced CLAUDE.md with Imports

## Project Overview
@path README.md

## API Documentation
@path docs/api/*.md

## Database Schema
@path database/schema.sql

## Testing Strategy
Test files are colocated with source files using *.test.ts pattern.
Run `npm test -- --coverage` for coverage report.

## Security Guidelines
- Validate all user inputs
- Use parameterized queries for database operations
- Never expose sensitive keys in code
- Follow OWASP security guidelines

## Performance Requirements
- Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1
- Bundle size budget: 200KB gzipped
- API response time: < 500ms p95

## CI/CD Pipeline
1. Pre-commit: Prettier, ESLint
2. PR checks: Tests, Type checking, Build
3. Deployment: Vercel preview on PR, production on main

## Do Not
- Edit generated files (*.generated.ts)
- Skip type checking
- Use `any` type without justification
- Modify database migrations after deployment
- Access filesystem outside project directory

Advanced Automations & Shortcuts

Eliminate repetitive tasks and accelerate your workflow with these battle-tested automations used by developers shipping production code with Claude Code.

🚀 Essential Shell Aliases

# Add to ~/.zshrc or ~/.bashrc
# Claudify - Fix command errors automatically
claudify() {
  local last_command=$(fc -ln -1)
  local output=$(eval "$last_command" 2>&1)
  claude -p "Fix this:\nCommand: $last_command\nOutput:\n$output"
}
alias fix='claudify'

# Quick code review
alias cr='git diff | claude -p "review this code"'

# Generate tests
alias gentest='claude "write tests for the current file"'

🔄 Git Hooks Integration

#!/bin/sh
# .git/hooks/pre-commit
# Auto-review and fix before commit

claude -p "Review staged files and fix any issues" \
  --headless --dangerously-skip-permissions

# Auto-format and add
git diff --cached --name-only | \
  grep -E '\.(js|ts)$' | \
  xargs prettier --write && \
  git add $(git diff --cached --name-only)

🤖 GitHub Actions with Claude

# .github/workflows/claude-pr.yml
name: Claude PR Action
on:
  issue_comment:
    types: [created]
    
jobs:
  claude-pr:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          command: ${{ github.event.comment.body }}
          auto_commit: true
          auto_push: true

Comment "@claude fix the failing tests" on any PR to have Claude automatically fix issues

⏱️ Time Savings

Debugging cycles:30+ seconds saved per issue

Git workflow:2-5 minutes saved per feature

Deployment:10-20 minutes saved per release

Hooks System: Automate Everything

The hooks system represents Claude Code's most underutilized capability, enabling shell command execution at specific lifecycle events. Configure hooks to automatically format code, run tests, or send notifications.

Advanced Hooks Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '🚀 Executing: $COMMAND' | tee -a ~/.claude/logs/commands.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write "$FILEPATH" 2>/dev/null || true"
          },
          {
            "type": "command",
            "command": "eslint --fix "$FILEPATH" 2>/dev/null || true"
          }
        ]
      },
      {
        "matcher": "Write",
        "condition": "$FILEPATH =~ \.(test|spec)\.(ts|tsx|js|jsx)$",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- "$FILEPATH" --watchAll=false"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "git add -A && git stash -u -m 'Claude Code auto-stash before: $PROMPT'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification "Task completed" with title "Claude Code"'"
          },
          {
            "type": "command",
            "command": "npm run type-check && npm run lint"
          }
        ]
      }
    ]
  }
}

Available Hook Events

• PreToolUse - Before any tool execution
• PostToolUse - After tool completion
• UserPromptSubmit - On user input
• Stop - When session ends
• Error - On error occurrence
• Success - On successful completion

Hook Variables

• $FILEPATH - Current file path
• $COMMAND - Executed command
• $PROMPT - User prompt text
• $TOOL - Tool being used
• $OUTPUT - Command output
• $ERROR - Error message

Real-World Case Studies

Learn from developers who have successfully shipped production applications using Claude Code as their primary development partner. These case studies demonstrate the transformative impact on solo developer productivity.

macOS App Built 95% by Claude

Developer: Indragie Karunaratne

🖥️

Product: Context - Native macOS debugging tool

Metrics: 20,000 lines total, <1,000 written by hand

Cost: $200/month for Claude API

Key Success Factors:

Detailed CLAUDE.md with Apple HIG guidelines
"Ultrathink" command for complex planning
Comprehensive 2,000-line release automation script

5 Parallel Claude Instances

Developer: Kieran Klaassen

📧

Product: Cora - AI email assistant

Workflow: 5 parallel Claude instances

Result: 2-person team output like 5+ developers

Revolutionary Approach:

100% of code written by Claude
All PRs opened by Claude
Developer role shifted to "engineering manager"

Years of Tech Debt in 6 Weeks

Developer: Orta Therox (Puzzmo)

🎮

Achievement: Completed massive technical migrations while maintaining roadmap

Completed in 6 weeks:

Converted hundreds of React Native components
Replaced 3 RedwoodJS systems
Migrated Jest to Vitest
Built iPad support
Updated to Node 22
Plus 10+ other major initiatives

Common Pattern: Developers report shipping products in weeks that would traditionally take months, with dramatically improved code quality and reduced cognitive overhead.

Hidden Power Features

--dangerously-skip-permissions

Bypass all prompts for full automation (use with caution)

claude --dangerously-skip-permissions "refactor all components"

--enable-architect

Enhanced large codebase handling with improved context management

claude --enable-architect "analyze the entire monorepo structure"

--mcp-debug

Enable debug logging for MCP server connections

claude --mcp-debug "list available tools"

--think

Allocate maximum reasoning budget for complex tasks

claude --think "design a distributed system architecture"

-p

Headless mode for piping and automation

git diff | claude -p "explain these changes"

--continue-on-error

Continue execution even if errors occur

claude --continue-on-error "fix all TypeScript errors"

Workflow Optimization Strategies

Performance Optimization

• Use architect mode for large codebases (>10k files)
• Scope contexts with --dir flag
• Leverage git worktrees for parallel development
• Enable caching with --cache flag
• Use --filter for specific file types

Security Best Practices

• Explicit directory allowlisting in MCP config
• Implement blocked command lists in hooks
• Store API keys in environment variables
• Regular audit of MCP permissions
• Use --dry-run for sensitive operations

Project Lifecycle Management

Manage entire project lifecycles from inception to deployment with Claude Code. These patterns help maintain context across sessions and ensure consistent progress on complex, long-running projects.

📋 Context Preservation Strategy

## Session Summary - [Date]

### Completed:
- Implemented user authentication
- Added PostgreSQL migrations
- Created API endpoints for /users
- Written 15 unit tests

### Current State:
- Auth system working with JWT
- Database connected and seeded
- Tests passing (15/15)

### Next Steps:
1. Add email verification
2. Implement password reset
3. Add rate limiting

### Context for Next Session:
- Using Passport.js for auth
- JWT tokens expire in 24h
- bcrypt rounds set to 10

🔄 Context Reconstruction

# Resuming work prompt template
I'm resuming work on [project]. 
Please read the CLAUDE.md file and 
session summary. Based on this:

1. Summarize current project state
2. Identify next logical steps
3. Highlight potential issues
4. Confirm understanding of architecture

Current focus: [specific task]

🐳 Monorepo Docker Setup

# docker-compose.yml for monorepo
version: '3.8'
services:
  frontend:
    build: ./packages/frontend
    ports: ["3000:3000"]
    volumes:
      - ./packages/frontend:/app
    environment:
      - REACT_APP_API_URL=http://localhost:8000

  backend:
    build: ./packages/backend
    ports: ["8000:8000"]
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app
    depends_on: [db]

  db:
    image: postgres:15
    ports: ["5432:5432"]
    environment:
      - POSTGRES_DB=app
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass

📅 Implementation Roadmap

Week 1-2: Foundation

• Create comprehensive CLAUDE.md files
• Set up Docker development environment
• Configure MCP servers
• Install essential automations

Week 3-4: Enhancement

• Implement custom slash commands
• Set up parallel development workflow
• Configure Git hooks
• Create session templates

Week 5+: Optimization

• Measure productivity metrics
• Refine context management
• Build project-specific tools
• Establish maintenance patterns

macOS-Specific Integrations

AppleScript Integration

Control system functions including Notes, Calendar, Contacts, and application automation

osascript -e 'tell application "System Events" to display dialog "Task complete!"'

Screenshot Integration

Use Control+V (not Command+V) to paste screenshots directly into Claude Code

# Take screenshot and analyze\nscreencapture -c && claude "analyze this UI"

Homebrew Integration

Natural language package installation and management

claude "install the tools needed for React development"

Troubleshooting Common Issues

Claude Code command not found

Ensure npm global bin directory is in PATH. Run: npm config get prefix

export PATH=$PATH:$(npm config get prefix)/bin

API key not recognized

Set the API key in environment variables or Claude config

export ANTHROPIC_API_KEY="sk-ant-..."
# Or use config file
claude config set api_key sk-ant-...

MCP server connection failed

Check server logs and ensure correct installation

claude --mcp-debug
# Check logs at ~/.claude/logs/

Permission denied errors

Ensure Claude Code has proper file system permissions

# Fix permissions
chmod +x ~/.claude/bin/*
# Or reinstall
npm uninstall -g @anthropic/claude-code
npm install -g @anthropic/claude-code

Hooks not executing

Verify hooks configuration and check for syntax errors

# Validate hooks.json
claude config validate
# Enable debug mode
export CLAUDE_DEBUG=true

Start Your Claude Code Journey

Begin with Desktop Commander and filesystem MCPs for core functionality, then gradually add database and framework-specific servers based on your stack. The investment in proper setup pays dividends through consistency, reduced context switching, and the ability to delegate complex multi-step operations to an AI assistant that understands your specific development environment and preferences.

Get Started with Claude Code Learn MCP Basics First

Advanced Claude Code Setup for macOS

Table of Contents

Installation & Setup

Prerequisites

Quick Start Guide

Pro Tips

Common Workflows

Solo Developer Productivity Workflows

📊 Productivity Metrics

⚡ Multi-Instance Strategy

Daily Workflow Routine

💰 Cost Analysis

Essential MCP Servers for Web Development

Desktop Commander MCP

Filesystem MCP

Git MCP Server

GitHub MCP

PostgreSQL MCP

Master CLAUDE.md Configuration

📁 Hierarchical Configuration Strategy

Basic CLAUDE.md Example

Advanced CLAUDE.md with Imports

Advanced Automations & Shortcuts

🚀 Essential Shell Aliases

🔄 Git Hooks Integration

🤖 GitHub Actions with Claude

⏱️ Time Savings

Hooks System: Automate Everything

Advanced Hooks Configuration

Available Hook Events

Hook Variables

Real-World Case Studies

macOS App Built 95% by Claude

5 Parallel Claude Instances

Years of Tech Debt in 6 Weeks

Hidden Power Features

Workflow Optimization Strategies

Performance Optimization

Security Best Practices

Project Lifecycle Management

📋 Context Preservation Strategy

🔄 Context Reconstruction

🐳 Monorepo Docker Setup

📅 Implementation Roadmap

Week 1-2: Foundation

Week 3-4: Enhancement

Week 5+: Optimization

macOS-Specific Integrations

AppleScript Integration

Screenshot Integration

Homebrew Integration

Troubleshooting Common Issues

Claude Code command not found

API key not recognized

MCP server connection failed

Permission denied errors

Hooks not executing

Start Your Claude Code Journey

Additional Resources

MCP Documentation

Official MCP Servers

Discord Community

Awesome MCP Servers

Anthropic Console

Video Tutorials