CLI Tool for Claude Code

Add subagents and commands from your terminal with the bwc CLI

Quick Install

npm install -g bwc-cli

Easy Installation

Install and manage subagents with simple commands

Status Monitoring

Check config, installed items, and health status

MCP Servers

Connect to external tools with Docker MCP integration

Project Config

Team-wide settings with version control

Installation

Use directly without installation

# Run any command with npx
npx bwc-cli@latest init
npx bwc-cli@latest add --agent python-pro
npx bwc-cli@latest list --agents

Core Commands

bwc init

Initialize configuration

# Initialize user level configuration (default)
bwc init

# Initialize project-level configuration
bwc init --project

# ⚠️ With project config, all installations default to project scope

bwc add

Add subagents or commands (defaults to project if project config exists)

# Add specific subagent
bwc add --agent python-pro

# Add specific command
bwc add --command dockerize

# Interactive mode (browse and select)
bwc add

# Force user-level install (when project config exists)
bwc add --agent python-pro --user

# Force project-level install (requires project config)
bwc add --agent python-pro --project

# Add MCP server with explicit scope
bwc add --mcp postgres --scope project

# Add Docker MCP server (uses Docker MCP Toolkit)
bwc add --mcp redis --docker-mcp

# Setup Docker MCP gateway
bwc add --setup

# Add MCP server with environment variables
bwc add --mcp postgres --docker-mcp --scope project -e DB_PASSWORD=secret API_KEY=abc123

💡 Interactive Mode: Use SPACE to select/deselect items, ENTER to confirm

bwc list

Browse available items

# List all items
bwc list

# List subagents only
bwc list --agents

# Show installed items
bwc list --installed

# Filter by category
bwc list --category language-specialists

bwc search

Search for subagents and commands

# Search both subagents and commands
bwc search python

# Search subagents only
bwc search python --agents

# Search commands only
bwc search docker --commands

bwc status

Display current BWC configuration status and health

# Show comprehensive status report
bwc status

# Verify actual MCP server installations
bwc status --verify-mcp

# Output in JSON format for scripting
bwc status --json

# Verbose output with deep health checks
bwc status --verbose --check

# Filter MCP servers by scope
bwc status --scope project
bwc status --scope user

💡 Status Report includes: Config scope (project/user), installed items, Claude CLI status, Docker MCP status, health checks, and MCP server verification (with --verify-mcp)

bwc install

Install all dependencies from configuration

# Install all items listed in config
bwc install

# Perfect for team onboarding:
# 1. Clone project with bwc.config.json
# 2. Run bwc install
# 3. All team members have same setup!

Configuration

Configuration Scope Behavior

🎯 Default Installation Behavior

• With project config (./bwc.config.json): All installations go to .claude/agents/ and .claude/commands/

• Without project config: Installations go to user level (~/.claude/agents/ and ~/.claude/commands/)

• MCP servers: Always require explicit --scope parameter

# After running: bwc init --project
bwc add --agent python-pro      # → ./claude/agents/
bwc add --command dockerize     # → ./claude/commands/
bwc add --mcp postgres --scope project  # Explicit scope needed
bwc add --agent rust-pro --user        # Override to user level
bwc add --agent golang-pro --project   # Force project level

Use Cases

Team Onboarding

Scaffold your Claude Code setup with your team

# Initialize project configuration
bwc init --project

# Add project-specific subagents
bwc add --agent backend-architect
bwc add --agent database-admin
bwc add --command dockerize

# Commit configuration
git add bwc.config.json
git commit -m "Add Claude Code configuration"

# Team members install dependencies
git clone <repo>
bwc install

Bulk Installation

Add multiple items at once

# Search for testing-related tools
bwc search test

# Add multiple items interactively
bwc add
# Select "Subagent"
# Select category or "All"
# Use SPACE to select multiple items
# Press ENTER to install all

CI/CD Integration

Automate Claude Code setup in your pipelines

# .github/workflows/setup.yml
- name: Install bwc CLI
  run: npm install -g bwc-cli
  
- name: Install Claude dependencies
  run: bwc install

🔌 MCP Servers

Connect Claude Code to external tools and services through MCP (Model Context Protocol)

🎯 Provider Selection Guide

BWC supports multiple MCP providers. Choose the right one for your needs:

🐳 Docker MCP Provider (Docker MCP Toolkit)

For containerized, locally-running servers

bwc add --mcp <name> --docker-mcp

✅ Secure container isolation
✅ Pre-configured servers from Docker Hub
✅ Automatic lifecycle management
⚠️ Requires Docker Desktop

🌐 Claude CLI Provider

For remote APIs and cloud services

bwc add --mcp <name> --transport sse --url <url>

✅ Connect to any HTTP/SSE endpoint
✅ Custom authentication headers
✅ No Docker requirement
⚠️ Requires network connectivity

⚠️ Important: The --docker-mcp flag is required to use Docker MCP. Without it, BWC will attempt to use Claude CLI.

📊 Provider Comparison

Feature	🐳 Docker MCP	🌐 Claude CLI
Command Syntax	`--docker-mcp`	`--transport --url`
Server Location	Local containers	Remote endpoints
Requirements	Docker Desktop	Network connectivity
Best For	Databases, file systems, dev tools	APIs, cloud services, SaaS tools
Security	Container isolation	HTTPS + Auth headers
Examples	postgres, redis, filesystem	Linear, GitHub API, OpenAI

Docker MCP Toolkit Integration

BWC CLI integrates with Docker MCP Toolkit for secure, containerized MCP servers.

🎯 Explicit selection: Use --docker-mcp flag to select Docker provider

🔒 Container isolation: Each server runs in a secure container

🚀 Simple management: Pre-configured servers from Docker Hub

🔑 Secure secrets: Docker Desktop manages all API keys

# Setup Docker MCP gateway (one-time)
bwc add --setup

# Add Docker MCP server (--docker-mcp flag is REQUIRED)
bwc add --mcp redis --docker-mcp

# Check Docker MCP status
bwc status --verbose

💡 Note: Docker MCP is no longer automatically selected. You must explicitly use the --docker-mcp flag to install Docker-based servers.

🎮 Interactive Mode Provider Selection

When Docker MCP is available, interactive mode lets you choose your provider

# Run interactive mode
bwc add

# If Docker MCP is available, you'll see:
? What would you like to add?
> MCP Server

? Select MCP provider:
> Docker MCP (containerized local servers)    # Choose for local servers
  Claude CLI (remote servers via SSE/HTTP)    # Choose for remote APIs

# Based on your selection:
# - Docker MCP: Lists available Docker servers
# - Claude CLI: Prompts for server name, URL, transport

💡 Tip: If Docker isn't available, BWC automatically uses the registry.

Quick Start

Get started with MCP servers using explicit commands

# Browse available MCP servers
bwc mcp list

# Install Docker MCP server (requires --docker-mcp flag)
bwc add --mcp postgres --docker-mcp

# Install for project only (team sharing)
bwc add --mcp postgres --docker-mcp --scope project

# Search for specific functionality
bwc mcp search database

# View server details
bwc mcp info postgres

Docker MCP Servers

Use Docker MCP for containerized, locally-running MCP servers

🚀 Setup Docker MCP Gateway

One-time setup to configure Docker MCP in Claude Code

# Setup Docker MCP gateway
bwc add --setup

# This configures Claude Code to use Docker MCP gateway
# Restart Claude Code after setup

📦 Add Docker MCP Servers

Install containerized MCP servers from Docker Hub(--docker-mcp flag is required!)

# ⚠️ IMPORTANT: --docker-mcp flag is REQUIRED for Docker servers
bwc add --mcp postgres --docker-mcp
bwc add --mcp redis --docker-mcp --scope project
bwc add --mcp mongodb --docker-mcp --scope user

# Without --docker-mcp, BWC will try to find the server in registry
# bwc add --mcp postgres  # ❌ This will NOT use Docker MCP!

# List available Docker MCP servers
docker mcp list

# Check which servers are running
docker mcp status

🐳 Popular Docker MCP Servers

postgresredismongodbelasticsearchmysqlsqlitegithubgitlabfilesystem

📋 Prerequisites: Docker Desktop must be installed and running.Download Docker Desktop →

MCP Server Installation Scopes

Control where and how MCP servers are configured

📍 Local Scope

• Default scope
• Current project only
• Not shared with team
• Personal configurations

bwc add --mcp redis --scope local

👤 User Scope

• Available across all projects
• Personal settings
• Not shared with team
• Stored in ~/.bwc/config.json

bwc add --mcp supabase --scope user

👥 Project Scope

• Configuration in version control
• Team members use same servers
• Shared configuration
• Stored in ./bwc.config.json

bwc add --mcp postgres --scope project

Environment Variables

Configure MCP servers with environment variables for API keys and secrets

# Add MCP server with environment variables
bwc add --mcp postgres --docker-mcp --scope project -e DB_PASSWORD=secret API_KEY=abc123

# Multiple environment variables
bwc add --mcp openai --scope project \
  -e OPENAI_API_KEY=sk-... \
  -e OPENAI_ORG_ID=org-...

# Environment variables are stored securely:
# - Project scope: Stored in .mcp.json (add to .gitignore!)
# - User/Local scope: Managed by Claude CLI or Docker Desktop

⚠️ Security Note: Never commit API keys to version control. Use environment variables or secrets management tools.

🔄 Using Multiple MCP Providers

BWC supports multiple MCP providers in the same project - mix and match as needed!

🎯 How Provider Selection Works

BWC selects providers based on your command flags:

# Docker MCP: Use --docker-mcp flag
bwc add --mcp postgres --docker-mcp              # ✅ Uses Docker
bwc add --mcp redis --docker-mcp --scope project # ✅ Uses Docker

# Claude CLI: Use --transport and --url flags
bwc add --mcp api-server --transport sse --url https://api.example.com  # ✅ Uses Claude CLI
bwc add --mcp rest-api --transport http --url https://api.service.com   # ✅ Uses Claude CLI

# Registry: No provider flags (searches registry)
bwc add --mcp some-server                        # 🔍 Searches registry

# Example: Mixed providers in same project
bwc add --mcp postgres --docker-mcp              # Local database via Docker
bwc add --mcp redis --docker-mcp                 # Cache via Docker
bwc add --mcp linear-server --transport sse \    # Project management via Claude CLI
  --url https://mcp.linear.app/sse \
  --header "Authorization: Bearer $LINEAR_API_KEY"

🐳 Use Docker MCP For:

• Local databases (PostgreSQL, Redis, MongoDB)
• File system operations
• Development tools
• Services requiring container isolation
• Pre-configured MCP servers from Docker Hub

🌐 Use Claude CLI For:

• Remote REST APIs
• SSE streaming endpoints
• Cloud services (AWS, Azure, GCP)
• Custom company APIs
• Services with complex authentication

📦 Mixed Provider Configuration

Example of using both providers in bwc.config.json

{
  "installed": {
    "mcpServers": {
      "postgres": {
        "provider": "docker",      // Docker MCP provider
        "transport": "stdio",
        "scope": "project"
      },
      "redis": {
        "provider": "docker",      // Docker MCP provider
        "transport": "stdio",
        "scope": "project"
      },
      "company-api": {
        "provider": "claude",      // Claude CLI provider
        "transport": "sse",
        "url": "https://api.company.com/sse",
        "headers": {
          "Authorization": "Bearer token"
        },
        "scope": "user"
      },
      "rest-service": {
        "provider": "claude",      // Claude CLI provider
        "transport": "http",
        "url": "https://api.service.com/v1",
        "headers": {
          "X-API-Key": "key123"
        },
        "scope": "project"
      }
    }
  }
}

✅ Best Practices for Mixed Providers:

• Use Docker MCP for development infrastructure (databases, caches)
• Use Claude CLI for external APIs and cloud services
• Check provider status with bwc status --verbose
• Docker servers start automatically with Docker Desktop
• Remote servers require network connectivity

Remote MCP Servers (Claude CLI)

Connect to remote MCP servers via SSE (Server-Sent Events) or HTTP APIs using Claude CLI

📡 SSE Transport (Real-time Streaming)

For servers that support Server-Sent Events for real-time communication

# Connect to SSE endpoint
bwc add --mcp linear-server --transport sse --url https://mcp.linear.app/sse --header "Authorization: Bearer token123"

# With multiple headers for authentication
bwc add --mcp streaming-api --scope user \
  --transport sse \
  --url https://api.example.com/v2/sse \
  --header "Authorization: Bearer token" \
  --header "X-Client-ID: client123"

🌐 HTTP Transport (REST APIs)

For traditional HTTP/REST API endpoints

# Connect to HTTP endpoint
bwc add --mcp http-service --transport http --url https://api.service.com/v1 --header "X-API-Key: key123"

# With custom headers and authentication
bwc add --mcp rest-service --scope project \
  --transport http \
  --url https://api.company.com/mcp \
  --header "X-API-Key: secret-key" \
  --header "Content-Type: application/json"

📝 Configuration Storage

How remote servers are stored in your configuration

// bwc.config.json
{
  "installed": {
    "mcpServers": {
      "remote-api": {
        "provider": "claude",
        "transport": "sse",
        "url": "https://api.example.com/sse",
        "headers": {
          "Authorization": "Bearer token123"
        },
        "scope": "user"
      },
      "http-service": {
        "provider": "claude",
        "transport": "http",
        "url": "https://api.service.com/v1",
        "headers": {
          "X-API-Key": "key123"
        },
        "scope": "project"
      }
    }
  }
}

💡 Tips for Remote Servers:

• Use HTTPS endpoints for secure communication
• Store sensitive tokens in environment variables
• SSE is ideal for real-time, streaming responses
• HTTP is suitable for request-response patterns
• Test connectivity with bwc status --verbose

💡 Example: Full-Stack Project with Mixed Providers

Real-world example using both Docker MCP and Claude CLI providers

# 1. Setup project configuration
bwc init --project

# 2. Add local development infrastructure (Docker MCP)
# ⚠️ Note: --docker-mcp flag is REQUIRED for each Docker server
bwc add --mcp postgres --docker-mcp --scope project     # Database
bwc add --mcp redis --docker-mcp --scope project        # Cache
bwc add --mcp filesystem --docker-mcp --scope project   # File operations

# 3. Add external APIs (Claude CLI for remote servers)
# Use --transport and --url for remote servers
bwc add --mcp linear-server --transport sse \
  --url https://mcp.linear.app/sse \
  --header "Authorization: Bearer $LINEAR_API_KEY" \
  --scope project

bwc add --mcp github-api --transport http \
  --url https://api.github.com \
  --header "Authorization: Bearer $GITHUB_TOKEN" \
  --scope project

# 4. Check all configured servers
bwc status --verbose

# Output shows mixed providers:
# 🔌 MCP Servers (5 installed):
#   ✓ postgres      [project]  docker/stdio    ✅
#   ✓ redis         [project]  docker/stdio    ✅
#   ✓ filesystem    [project]  docker/stdio    ✅
#   ✓ linear-server [project]  claude/sse      ✅
#   ✓ github-api    [project]  claude/http     ✅

# 5. Team members can install everything with one command
git clone <repo>
bwc install  # Automatically installs both Docker and Claude CLI servers

Team Collaboration

Share MCP servers with your team

# Team lead sets up project MCP servers
bwc init --project
bwc add --mcp postgres --scope project
bwc add --mcp github --scope project

# Commit configuration
git add bwc.config.json
git commit -m "Add team MCP servers"

# Team members clone and install
git clone <repo>
bwc install  # Installs all configured MCP servers

List and Search MCP Servers

Find and manage installed servers

# List all servers
bwc mcp list

# List user-installed servers
bwc mcp list --user

# List project-installed servers
bwc mcp list --project

MCP Server Providers

BWC supports multiple MCP server providers for maximum flexibility

🐳

Docker MCP

Containerized servers with secure isolation

🤖

Claude CLI

Native integration with Claude Code

BWC uses Claude CLI by default. You have to specify --docker-mcp flag to use Docker MCP.

Popular MCP Servers

redis

Database operations

github

GitHub API

context7

Contextual AI

stripe

Payments

slack

Team chat

notion

Knowledge base

atlassian

Issue tracking

elastic

Search & analytics

View all 100+ servers at buildwithclaude.com/mcp-servers

🔍 MCP Server Verification

The --verify-mcp flag performs deep verification of MCP server installations

Basic vs Verified Status

Basic Status (Fast)

bwc status

# Shows configuration-based status
# ✓ Quick check
# ✓ No external calls
# ✓ Shows what's in config files

Verified Status (Thorough)

bwc status --verify-mcp

# Verifies actual installations
# ✓ Checks Claude CLI servers
# ✓ Checks Docker MCP servers
# ✓ Tests connectivity
# ✓ Shows fix commands

Example Verification Output

When servers are configured but not actually installed

$ bwc status --verify-mcp

🔌 MCP Servers (3 configured, verification enabled):
  ⚠️ postgres       [project] docker/stdio   GATEWAY NOT CONFIGURED
  ⚠️ redis          [user]    docker/stdio   NOT INSTALLED  
  ✅ linear-server  [project] claude/sse     Connected

📋 MCP Verification Issues Found:
  
  postgres:
    Issue: Docker MCP gateway not configured in Claude CLI
    Fix:   1. Run: bwc add --setup
           2. Restart Claude Code
           3. Then: docker mcp server add postgres
  
  redis:
    Issue: Server not installed in Docker MCP
    Fix:   docker mcp server add redis

Verification Status Icons

✅ Connected/Installed: Server is properly installed and working

⚠️ NOT INSTALLED: Configured in BWC but not in Claude CLI or Docker MCP

⚠️ GATEWAY NOT CONFIGURED: Docker gateway needs setup via bwc add --setup

❌ Error: Connection or configuration error

Common Issues and Fixes

Docker Gateway Not Configured

The verification shows Docker servers need the gateway

# Fix in order:
1. bwc add --setup           # Setup Docker MCP gateway
2. Restart Claude Code       # Activate the gateway
3. docker mcp server add <name>  # Install the server

Claude CLI Server Not Found

Remote servers configured but not in Claude CLI

# For SSE servers:
claude mcp add <name> --transport sse --url <url>

# For HTTP servers:
claude mcp add <name> --transport http --url <url>

When to Use MCP Verification

✓ MCP servers appear configured but don't work in Claude Code
✓ After team member clones project with bwc.config.json
✓ Debugging "server not found" errors
✓ Verifying Docker gateway setup
✓ Checking remote server connectivity

🔍 MCP Server Verification

Verify that your MCP servers are properly installed and configured with the --verify-mcp flag.

How Verification Works

The bwc status --verify-mcp command performs deep verification of your MCP server installations:

• ✅ Checks if servers are configured in BWC
• ✅ Verifies actual installation in Claude Code
• ✅ Detects missing or misconfigured servers
• ✅ Provides fix commands for issues
• ✅ Reminds about Docker gateway setup when needed

Using MCP Verification

# Basic status check
bwc status

# Deep MCP server verification
bwc status --verify-mcp

# JSON output for scripting
bwc status --verify-mcp --json

Example Verification Output

✓ BWC Configuration Status

Configuration: /path/to/project/bwc.config.json (project)

📦 Installed Items:
  Subagents: 3
  Commands: 2
  MCP Servers: 5

🔌 MCP Server Verification:
  ✓ postgres (Docker) - Installed and configured
  ✓ redis (Docker) - Installed and configured
  ✓ linear-server (SSE) - Configured in .mcp.json
  ⚠ github (Docker) - Not installed
    Fix: bwc add --mcp github --docker-mcp
    Note: Run 'bwc add --setup' to configure Docker gateway if needed
  ⚠ api-server (HTTP) - Missing from .mcp.json
    Fix: bwc add --mcp api-server --transport http --url https://api.example.com --scope project

Common Verification Issues

Docker gateway not configured:

Run bwc add --setup to configure the Docker MCP gateway

Server missing from .mcp.json:

Remote servers need to be in .mcp.json for team sharing. Re-add with --scope project

Docker server not enabled:

Use the provided fix command to enable the server in Docker MCP

Troubleshooting

Configuration not found

Run bwc init to create configuration

Check configuration status

Run bwc status --verbose to see detailed configuration and health information

Can't add remote server when Docker is available

This issue has been fixed! BWC no longer automatically selects Docker MCP.

Solution: Use explicit flags to select your provider:

• For Docker: bwc add --mcp postgres --docker-mcp
• For Remote: bwc add --mcp api --transport sse --url https://...

Provider selection confusion

Not sure which provider BWC is using?

• Run bwc status --verbose to see provider for each server
• Look for docker/stdio or claude/sse in the output
• Check your bwc.config.json for the "provider" field

Docker MCP not working

Ensure Docker Desktop is running. Run bwc add --setup to configure the Docker MCP gateway

Remember: Always use --docker-mcp flag when adding Docker servers!

Remote MCP server connection failed

For remote servers via Claude CLI:

• Verify the URL is accessible: curl -I <url>
• Check authentication headers are correct
• Ensure Claude CLI is installed: npm install -g @anthropic/claude-cli
• Use --transport sse or --transport http as appropriate

MCP servers from old version

BWC automatically migrates legacy MCP server configurations. Old string arrays are converted to the new format with 'docker' as the default provider

Failed to fetch registry

Check your internet connection. The CLI needs access to buildwithclaude.com

Permission denied

On macOS/Linux, you may need to use sudo npm install -g bwc-cli

Interactive mode not selecting

Use SPACE to select items (not Enter). Selected items show a ● marker. Press ENTER only to confirm.

Next Steps

→ Browse available subagents → Explore slash commands → Browse MCP servers → Contribute your own subagents → Report issues or suggest features