MCP CLI

A command-line interface for interacting with MCP (model context protocol) servers. MCP CLI allows you to manage and chat with different types of AI-powered servers, supporting both on-demand (stdio) and long-running (SSE) server processes.

MCP CLI supports two types of servers, each with different use cases:

1. stdio Servers (On-demand)

• Spawns a new process for each chat session
• Automatically managed by the CLI
• Perfect for stateless tools and simple integrations
• No manual server management required

2. SSE Servers (Long-running)

• Runs as a persistent process
• Must be started before chatting
• Ideal for stateful applications or services that need to maintain connections
• Requires manual server management

Installation

npm install -g @im2nguyen/mcp

Quick Start

1. Create a configuration file (mcp-config.json):

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["path/to/calculator/server.js"],
      "type": "stdio"
    }
  }
}

2. Import your configuration:

mcp config import mcp-config.json

3. Start chatting:

mcp chat

That's it! The CLI will handle spawning the server process and managing the connection.

Common Workflows

Basic Workflow (stdio servers)

1. Configure your server:

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["./calculator-server.js"],
      "type": "stdio"
    }
  }
}

2. Import and start chatting:

mcp config import mcp-config.json
mcp chat

Advanced Workflow (SSE servers)

1. Configure your server:

{
  "mcpServers": {
    "weather-api": {
      "command": "node",
      "args": ["./weather-server.js"],
      "type": "sse",
      "url": "http://localhost:3000"
    }
  }
}

2. Import configuration:

mcp config import mcp-config.json

3. Start the server:

mcp server start weather-api

4. Begin chatting:

mcp chat -s weather-api

5. When finished, stop the server:

mcp server stop weather-api

Non-Interactive Workflow (Piped Commands)

MCP CLI supports non-interactive mode where you can pipe commands directly to it, which is useful for scripting or one-time queries:

1. Send a single query to a server:

echo "what is 20+20?" | mcp chat -s calculator
40

2. Process multiple queries from a file:

cat queries.txt | mcp chat -s calculator

3. Use in shell scripts or command chains:

# Example: Use in a shell script
result=$(echo "what is 20+20?" | mcp chat -s calculator)
echo "The result is: $result"

# Example: Chain with other commands
echo "what is 20+20?" | mcp chat -s calculator | grep -o "[0-9]*"

When using piped input:

• No welcome messages or headers are displayed
• Only the direct response is output (no "Assistant:" prefix)
• Perfect for automation and command-line integration

Command Reference

Server Management

# List all configured servers and their status
mcp server list

# View detailed server information
mcp server info <server-id>

# Start a server (required for SSE servers)
mcp server start <server-id>
mcp server start <server-id> --debug  # Run in debug mode

# Stop a server
mcp server stop <server-id>

# Stop all running servers
mcp server stop-all

Chat

# Start a chat session
mcp chat                           # Interactive server selection
mcp chat -s <server-id>           # Connect to specific server

# Use different LLM providers
mcp chat -p anthropic             # Use Anthropic (default)
mcp chat -p openai                # Use OpenAI

# Specify models
mcp chat -m claude-3-5-sonnet     # Use specific model

# Non-interactive usage (piped input)
echo "query" | mcp chat -s <server-id>

Chat Options:

• -s, --server <id>: Specify server ID
• -p, --provider <provider>: LLM provider (anthropic or openai)
• -m, --model <model>: Model name (defaults: claude-3-5-sonnet-20241022 for Anthropic, gpt-4o for OpenAI)

Configuration Management

# Import server configurations
mcp config import <file>

# Export current configurations
mcp config export <file>

# View current configuration
mcp config show

# Manage log directory
mcp config set-logs-dir <path>    # Set custom logs directory
mcp config get-logs-dir           # Show current logs directory

Logging and Debugging

MCP CLI provides comprehensive logging capabilities:

• Default log location: ~/mcp/logs
• Server logs: ~/mcp/logs/server-{id}.log
• Custom log directory: mcp config set-logs-dir <path>

Best Practices

1. Server Type Selection:

   • Use stdio servers for simple, stateless tools
   • Use SSE servers for stateful applications or when persistence is needed

2. Process Management:

   • Let the CLI manage stdio server processes
   • Manually manage SSE server lifecycles
   • Use mcp server stop-all before shutting down

3. Logging:

   • Check server logs for troubleshooting
   • Enable debug logging for detailed information
   • Configure custom log directory for better organization

License

MIT