mcp-cli-philschmid

philschmid/mcp-cli

Repository: https://github.com/philschmid/mcp-cli

A lightweight, Bun-based CLI for interacting with MCP servers from the shell. Designed for AI coding agents (Gemini CLI, Claude Code, etc.) and shell scripting workflows.

Why Use It

Traditional MCP integration loads entire tool schemas into the AI context window, consuming thousands of tokens. mcp-cli enables dynamic, on-demand discovery — the agent only fetches schemas for tools it actually needs.

Key advantages:

• Token efficiency: Discover tools incrementally instead of loading all schemas upfront
• Connection pooling: Lazy-spawn daemons keep connections warm (60s idle timeout)
• Shell-native: JSON output compatible with pipes and jq for chaining
• Minimal footprint: Fast startup via Bun runtime

Installation

# Via install script
curl -fsSL https://raw.githubusercontent.com/philschmid/mcp-cli/main/install.sh | bash

# Via Bun
bun install -g https://github.com/philschmid/mcp-cli

Core Commands

Command	Purpose
mcp-cli	List all servers and tools
mcp-cli -d	List all servers and tools with descriptions
mcp-cli info <server>	Show all tools available in a server
mcp-cli info <server> <tool>	Display complete tool JSON schema
mcp-cli grep "<pattern>"	Search tools by name using glob pattern
mcp-cli call <server> <tool> <json>	Execute a tool with JSON arguments

Recommended Workflow (Discover → Explore → Inspect → Execute)

# 1. Discover — list all servers and available tools
mcp-cli
mcp-cli -d  # with descriptions

# 2. Explore — view tools for a specific server
mcp-cli info filesystem

# 3. Inspect — examine a specific tool's schema
mcp-cli info filesystem read_file

# 4. Execute — call the tool with arguments
mcp-cli call filesystem read_file '{"path": "./README.md"}'

Configuration

Create mcp_servers.json in one of these locations (searched in order):

1. $MCP_CONFIG environment variable
2. -c <path> command-line argument
3. Current directory
4. ~/.config/mcp/

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "web": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-web"]
    }
  }
}

Tool Filtering

Control which tools are exposed per server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "allowedTools": ["read_file", "list_directory"],
      "disabledTools": ["write_file"]
    }
  }
}

Environment Variable Substitution

{
  "mcpServers": {
    "api": {
      "command": "node",
      "args": ["api-server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Missing variables cause errors unless MCP_STRICT_ENV=false.

Shell Composition Examples

# Pipe JSON from stdin
echo '{"path": "./file"}' | mcp-cli call filesystem read_file

# Chain with jq
mcp-cli call filesystem list_directory '{"path": "."}' | jq '.[] | .name'

# Search for tools matching a pattern
mcp-cli grep "read*"

Exit Codes

Code	Meaning
0	Success
1	Client error
2	Server error
3	Network issue

When to Use mcp-cli vs Native MCP Integration

Scenario	Recommendation
AI agent needs a few specific tools	mcp-cli (discover on demand, save tokens)
Shell scripts calling MCP tools	mcp-cli (native shell integration)
Debugging MCP server issues	mcp-cli (inspect schemas, test calls)
Full IDE integration with many tools	Native MCP (persistent connection, all tools available)
CI/CD pipelines	mcp-cli (scriptable, JSON output)