mcp-cli-tool

# mcp-cli Tool > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview `mcp-cli` is a lightweight, Bun-based CLI for interacting with [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers. It provides: - **On-demand schema loading** - Only fetch tool schemas when needed, saving AI context tokens - **Shell composability** - JSON output for piping with `jq`, chaining, and scripting - **Connection pooling** - Lazy-spawn daemon keeps connections warm (60s idle timeout) - **Universal support** - Works with both stdio and HTTP MCP servers - **Tool filtering** - Allow/disable specific tools per server via config **Use cases:** - AI agents accessing MCP tools without loading full schemas into context - Shell scripts automating MCP server interactions - Discovering and exploring available MCP capabilities ## Installation ### Quick Install (Recommended) ```bash curl -fsSL https://raw.githubusercontent.com/philschmid/mcp-cli/main/install.sh | bash ``` ### Manual Install (Requires Bun) ```bash bun install -g https://github.com/philschmid/mcp-cli ``` ### Verify Installation ```bash mcp-cli --version ``` ## Configuration ### Config File Location Create `mcp_servers.json` in one of these locations (searched in order): 1. Path from `MCP_CONFIG_PATH` environment variable 2. Path from `-c/--config` CLI argument 3. `./mcp_servers.json` (current directory) 4. `~/.mcp_servers.json` 5. `~/.config/mcp/mcp_servers.json` ### Basic Config Format Compatible with Claude Desktop, Gemini, and VS Code: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "." ] }, "github": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } }, "deepwiki": { "url": "https://mcp.deepwiki.com/mcp" } } } ``` ### Advanced Config Options ```json { "mcpServers": { "local-server": { "command": "node", "args": ["./server.js"], "env": { "API_KEY": "${API_KEY}" }, "cwd": "/path/to/directory", "allowedTools": ["read_*", "list_*"], "disabledTools": ["delete_*"] }, "remote-server": { "url": "https://mcp.example.com", "headers": { "Authorization": "Bearer ${TOKEN}" } } } } ``` ### Environment Variable Substitution Use `${VAR_NAME}` syntax anywhere in config: ```json { "mcpServers": { "api-server": { "command": "node", "args": ["server.js"], "env": { "DATABASE_URL": "${DATABASE_URL}", "API_KEY": "${API_KEY}" } } } } ``` **Control behavior:** - `MCP_STRICT_ENV=true` (default): Error on missing variables - `MCP_STRICT_ENV=false`: Use empty values with warning ### Tool Filtering Restrict available tools using glob patterns: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."], "allowedTools": ["read_file", "list_directory"], "disabledTools": ["delete_file"] } } } ``` **Rules:** - `allowedTools`: Whitelist (supports `*`, `?` glob patterns) - `disabledTools`: Blacklist (takes precedence over allowedTools) - Applies to all operations (info, grep, call) **Examples:** ```json // Only read operations "allowedTools": ["read_*", "list_*", "search_*"] // Disable destructive operations "disabledTools": ["delete_*", "write_*", "create_*"] // Combine filters "allowedTools": ["*file*"], "disabledTools": ["delete_file"] ``` ## Core Commands ### List All Servers and Tools ```bash # Basic listing mcp-cli # With descriptions mcp-cli -d ``` **Output:** ``` github • search_repositories • get_file_contents • create_or_update_file filesystem • read_file • write_file • list_directory ``` ### Search Tools by Pattern ```bash # Find file-related tools mcp-cli grep "*file*" # Search with descriptions mcp-cli grep "*search*" -d ``` **Output:** ``` github/get_file_contents github/create_or_update_file filesystem/read_file filesystem/write_file ``` ### View Server Details ```bash mcp-cli info <server> ``` **Example:** ```bash mcp-cli info github ``` **Output:** ``` Server: github Transport: stdio Command: npx -y @modelcontextprotocol/server-github Tools (12): search_repositories Search for GitHub repositories Parameters: • query (string, required) - Search query • page (number, optional) - Page number ... ``` ### View Tool Schema Both formats work: ```bash mcp-cli info <server> <tool> mcp-cli info <server>/<tool> ``` **Example:** ```bash mcp-cli info github search_repositories ``` **Output:** ``` Tool: search_repositories Server: github Description: Search for GitHub repositories Input Schema: { "type": "object", "properties": { "query": { "type": "string", "description": "Search query" }, "page": { "type": "number" } }, "required": ["query"] } ``` ### Call a Tool ```bash # Inline JSON mcp-cli call <server> <tool> '{"key": "value"}' # From stdin (auto-detected, no '-' needed) echo '{"path": "./file"}' | mcp-cli call <server> <tool> # Heredoc for complex JSON mcp-cli call <server> <tool> <<EOF {"content": "Text with 'quotes' and \"escapes\""} EOF ``` **Example:** ```bash mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}' ``` **Output (JSON):** ```json { "content": [ { "type": "text", "text": "{\"items\": [{\"name\": \"mcp-cli\", \"url\": \"...\"}]}" } ] } ``` ## Practical Usage Patterns ### 1. Discover → Inspect → Execute Workflow ```bash # Step 1: List available servers mcp-cli # Step 2: View server tools mcp-cli info filesystem # Step 3: Get tool schema mcp-cli info filesystem read_file # Step 4: Call the tool mcp-cli call filesystem read_file '{"path": "./README.md"}' ``` ### 2. Pipe JSON with jq ```bash # Extract specific field mcp-cli call github search_repositories '{"query": "mcp"}' | jq '.content[0].text' # Parse nested JSON mcp-cli call github search_repositories '{"query": "mcp"}' \ | jq -r '.content[0].text | fromjson | .items[].html_url' # Filter results mcp-cli call filesystem list_directory '{"path": "."}' \ | jq -r '.content[0].text | split("\n")[] | select(endswith(".md"))' ``` ### 3. Chain Multiple MCP Calls ```bash # Search and read first result mcp-cli call filesystem search_files '{"path": "src/", "pattern": "*.ts"}' \ | jq -r '.content[0].text | split("\n")[0]' \ | xargs -I {} mcp-cli call filesystem read_file '{"path": "{}"}' # Process all matching files mcp-cli call filesystem search_files '{"path": ".", "pattern": "*.md"}' \ | jq -r '.content[0].text | split("\n")[]' \ | while read file; do echo "=== $file ===" mcp-cli call filesystem read_file "{\"path\": \"$file\"}" | jq -r '.content[0].text' done ``` ### 4. Error Handling in Scripts ```bash # Conditional execution mcp-cli call filesystem list_directory '{"path": "."}' \ | jq -e '.content[0].text | contains("README.md")' \ && mcp-cli call filesystem read_file '{"path": "./README.md"}' # Fallback on error if result=$(mcp-cli call filesystem read_file '{"path": "./config.json"}' 2>/dev/null); then echo "$result" | jq '.content[0].text | fromjson' else echo "File not found, using defaults" fi ``` ### 5. Save Output to File ```bash mcp-cli call github get_file_contents '{"owner": "user", "repo": "project", "path": "src/main.ts"}' \ | jq -r '.content[0].text' > main.ts ``` ### 6. Aggregate Results from Multiple Servers ```bash { mcp-cli call github search_repositories '{"query": "mcp", "per_page": 3}' mcp-cli call filesystem list_directory '{"path": "./src"}' } | jq -s '.' ``` ### 7. Complex JSON Arguments For JSON with special characters, use stdin to avoid shell escaping: ```bash # Heredoc (recommended) mcp-cli call server tool <<EOF { "content": "Text with 'single quotes' and \"double quotes\"", "metadata": { "nested": "value" } } EOF # From file cat args.json | mcp-cli call server tool # Using jq to build complex JSON jq -n '{query: "mcp", filters: ["active", "starred"]}' | mcp-cli call github search