Claude MCP CLI

A command-line interface for interacting with Model Context Protocol (MCP) servers. Supports both stdio and HTTP transports with daemon mode for optimal performance.

Features

• Full MCP Support: Tools, resources, prompts, and server management
• Dual Transport: stdio (subprocess) and HTTP/StreamableHTTP servers
• Daemon Mode: Persistent background service with connection pooling
• Project-Local Configuration: Per-project and global configuration support
• Auto-Shutdown: Daemon automatically stops after inactivity period
• OAuth Authentication: OAuth 2.1 support for compatible servers

Quick Start

Installation

Option 1: Install from npm (Global)

# Install globally
npm install -g claude-mcp-cli

# Now available anywhere as:
claude-mcp-cli --help
# or
mcp-cli --help

Option 2: Build from source

# Clone repository
git clone https://github.com/anthropics/claude-mcp-cli.git
cd claude-mcp-cli

# Build from source
make build

# Or install to GOPATH/bin
make install

Configuration

Create a configuration file at ~/.claude-mcp-cli/config.json (global) or ./.claude-mcp-cli/config.json (project-specific):

{
  "mcpServers": {
    "desktop-commander": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-desktop-commander@latest"],
      "env": {}
    },
    "linkup": {
      "type": "http",
      "url": "https://api.linkup.so/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configuration Search Order:

1. ./.claude-mcp-cli/config.json (current directory - project-specific)
2. ~/.claude-mcp-cli/config.json (home directory - global)

Basic Usage

# List available servers
claude-mcp-cli server list

# Check server connectivity
claude-mcp-cli server check -s linkup

# List tools on a server
claude-mcp-cli tool list -s desktop-commander

# Call a tool
claude-mcp-cli tool call search -s linkup -i '{"query": "MCP protocol"}'

# Read a resource
claude-mcp-cli resource read file:///path/to/file -s my-server

# Execute a prompt
claude-mcp-cli prompt call summary -s my-server -a '{"text": "Long text..."}'

Daemon Mode

The CLI includes a daemon mode that runs as a persistent background service, dramatically improving performance by maintaining server connections.

Performance Benefits

• First Request: ~2-5 seconds (server startup + connection)
• Subsequent Requests: <100ms (warm connection via daemon)
• Connection Pooling: Daemon maintains active connections to all servers

Daemon Management

# Check daemon status
claude-mcp-cli daemon status

# Start daemon manually (usually auto-starts)
claude-mcp-cli daemon start

# Stop daemon
claude-mcp-cli daemon stop

# Start daemon server (used internally)
claude-mcp-cli serve --daemon

Daemon Architecture

• Project-Local: Each project directory gets its own daemon instance
• Location: ./.claude-mcp-cli/ in current working directory
• Unix Socket: daemon.sock for RPC communication
• PID File: daemon.pid tracks running daemon
• Auto-Shutdown: Stops after 20 minutes of inactivity (configurable)
• Auto-Start: Commands automatically start daemon if not running

Inactivity Timer

# Default: 20 minutes
claude-mcp-cli serve --daemon

# Custom timeout
claude-mcp-cli serve --daemon --inactivity 30

Commands

Server Commands

List Servers

claude-mcp-cli server list

Lists all configured MCP servers.

Check Server

# Check specific server
claude-mcp-cli server check -s <server-name>

# Check all servers
claude-mcp-cli server check

Tests connectivity and shows available tools count.

Tool Commands

List Tools

claude-mcp-cli tool list -s <server-name>

Lists all tools with descriptions. Results saved to ~/.claude-mcp-cli/tool-lists/.

Get Tool Details

claude-mcp-cli tool get <tool-name> -s <server-name>

Shows tool description and input schema.

Call Tool

claude-mcp-cli tool call <tool-name> -s <server-name> -i '{"param": "value"}'

Executes a tool with JSON arguments. Results saved to ~/.claude-mcp-cli/tool-results/.

Resource Commands

List Resources

claude-mcp-cli resource list -s <server-name>

Lists all available resources with URIs and MIME types.

Get Resource Details

claude-mcp-cli resource get <uri> -s <server-name>

Shows resource metadata.

Read Resource

claude-mcp-cli resource read <uri> -s <server-name>

Reads and displays resource content. Results saved to ~/.claude-mcp-cli/resources/.

Prompt Commands

List Prompts

claude-mcp-cli prompt list -s <server-name>

Lists all available prompts.

Get Prompt Details

claude-mcp-cli prompt get <prompt-name> -s <server-name>

Shows prompt description and required arguments.

Call Prompt

claude-mcp-cli prompt call <prompt-name> -s <server-name> -a '{"arg": "value"}'

Executes a prompt with JSON arguments. Results saved to ~/.claude-mcp-cli/prompts/.

Authentication Commands

Login

claude-mcp-cli auth login -s <server-name>

Starts OAuth 2.1 authentication flow.

Logout

# Logout from specific server
claude-mcp-cli auth logout -s <server-name>

# Logout from all servers
claude-mcp-cli auth logout

Check Status

# Check all servers
claude-mcp-cli auth status

# Check specific server
claude-mcp-cli auth status -s <server-name>

Configuration Examples

stdio Server (subprocess)

{
  "mcpServers": {
    "desktop-commander": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-desktop-commander@latest"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

HTTP Server

{
  "mcpServers": {
    "linkup": {
      "type": "http",
      "url": "https://api.linkup.so/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  }
}

Multiple Servers

{
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "./my-mcp-server",
      "args": ["--debug"],
      "env": {}
    },
    "cloud-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "your-key"
      }
    }
  }
}

Directory Structure

~/.claude-mcp-cli/          # Global configuration
├── config.json             # Server definitions
├── tool-lists/             # Cached tool lists (timestamped)
├── tool-results/           # Tool execution results
├── resources/              # Resource read results
├── prompts/                # Prompt execution results
└── tokens.json             # OAuth tokens

./.claude-mcp-cli/          # Project-local (per directory)
├── config.json             # Project-specific servers
├── daemon.sock             # Unix socket for RPC
└── daemon.pid              # Daemon process ID

Architecture

Built with:

• Cobra: CLI framework
• mcp-go: MCP protocol implementation
• Go RPC: Daemon communication
• Unix Sockets: IPC for daemon mode

Transport Types

1. stdio: Spawns subprocess, communicates via stdin/stdout

   • Best for local tools and development
   • Automatic process lifecycle management

2. HTTP/StreamableHTTP: REST API communication

   • Best for cloud services and remote servers
   • Supports custom headers for authentication

Development

# Build
make build

# Run tests
make test

# Test with coverage
make coverage

# Clean build artifacts
make clean

# Update dependencies
make deps

Troubleshooting

Daemon Won't Start

# Check if already running
claude-mcp-cli daemon status

# Stop existing daemon
claude-mcp-cli daemon stop

# Remove stale socket/PID files
rm -f ./.claude-mcp-cli/daemon.sock ./.claude-mcp-cli/daemon.pid

# Start fresh
claude-mcp-cli daemon start

Server Connection Fails

# Verify server configuration
cat ~/.claude-mcp-cli/config.json

# Check server directly
claude-mcp-cli server check -s <server-name>

# For stdio servers, verify command exists
which npx

# For HTTP servers, verify URL and auth
curl -H "Authorization: Bearer TOKEN" https://api.example.com/mcp

Tools Not Found

# Refresh tool list
claude-mcp-cli tool list -s <server-name>

# Check saved tool lists
ls -la ~/.claude-mcp-cli/tool-lists/

# Verify server supports tools
claude-mcp-cli server check -s <server-name>

Examples

Working with Files (stdio)

# List file operations
claude-mcp-cli tool list -s desktop-commander

# Read a file
claude-mcp-cli tool call read_file -s desktop-commander \
  -i '{"path": "/path/to/file.txt"}'

Web Search (HTTP)

# Search the web
claude-mcp-cli tool call linkup-search -s linkup \
  -i '{"query": "Model Context Protocol", "depth": "standard"}'

# Fetch URL content
claude-mcp-cli tool call linkup-fetch -s linkup \
  -i '{"url": "https://example.com", "renderJs": false}'

Using Prompts

# List available prompts
claude-mcp-cli prompt list -s my-server

# Execute a summarization prompt
claude-mcp-cli prompt call summarize -s my-server \
  -a '{"text": "Long article text here...", "length": "brief"}'

License

See LICENSE file for details.

Contributing

Contributions welcome! Please submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.