AgentToolHub
Skill

mcp-cli

mcp-cli — a Claude Code skill from philschmid/mcp-cli

Features

  • ✓🪶 **Lightweight** - Minimal dependencies, fast startup
  • ✓📦 **Single Binary** - Compile to standalone executable via `bun build --compile`
  • ✓🔧 **Shell-Friendly** - JSON output for call, pipes with `jq`, chaining support
  • ✓🤖 **Agent-Optimized** - Designed for AI coding agents (Gemini CLI, Claude Code, etc.)
  • ✓🔌 **Universal** - Supports both stdio and HTTP MCP servers
  • ✓⚡ **Connection Pooling** - Lazy-spawn daemon keeps connections warm (60s idle timeout)
  • ✓� **Tool Filtering** - Allow/disable specific tools per server via config
  • ✓📋 **Server Instructions** - Display MCP server instructions in output
  • ✓�💡 **Actionable Errors** - Structured error messages with available servers and recovery suggestions

Installation Guide

bash
bun install https://github.com/philschmid/mcp-cli

Commands

bash
# Run in development
bun run dev

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

# Run all tests (unit + integration)
bun test

# Run only unit tests (fast)
bun test tests/config.test.ts tests/output.test.ts tests/client.test.ts

# Run integration tests (requires MCP server, ~35s)
bun test tests/integration/

# Build single executable
bun run build

# Build for all platforms
bun run build:all

Local Testing

Test the CLI locally without compiling by using bun link:

bash
# Link the package globally (run once)
bun link

# Now you can use 'mcp-cli' anywhere
mcp-cli --help
mcp-cli call filesystem read_file '{"path": "./README.md"}'

# Or run directly during development
bun run dev --help
bun run dev info filesystem

To unlink when done:

bash
bun unlink

Releasing

Releases are automated via GitHub Actions. Use the release script:

bash
./scripts/release.sh 0.2.0

Error Messages

All errors include actionable recovery suggestions, optimized for both humans and AI agents:

text
Error [AMBIGUOUS_COMMAND]: Ambiguous command: did you mean to call a tool or view info?
  Details: Received: mcp-cli filesystem read_file
  Suggestion: Use 'mcp-cli call filesystem read_file' to execute, or 'mcp-cli info filesystem read_file' to view schema

Error [UNKNOWN_SUBCOMMAND]: Unknown subcommand: "run"
  Details: Valid subcommands: info, grep, call
  Suggestion: Did you mean 'mcp-cli call'?

Error [SERVER_NOT_FOUND]: Server "github" not found in config
  Details: Available servers: filesystem, sqlite
  Suggestion: Use one of: mcp-cli info filesystem, mcp-cli info sqlite

Error [TOOL_NOT_FOUND]: Tool "search" not found in server "filesystem"
  Details: Available tools: read_file, write_file, list_directory (+5 more)
  Suggestion: Run 'mcp-cli info filesystem' to see all available tools

Error [INVALID_JSON_ARGUMENTS]: Invalid JSON in tool arguments
  Details: Parse error: Unexpected identifier "test"
  Suggestion: Arguments must be valid JSON. Use single quotes: '{"key": "value"}'

Reviews