mcp-cli

Access MCP servers through the command line. MCP enables interaction with external systems like GitHub, filesystems, databases, and APIs.

When to Use

• To interactively call an MCP (Model Context Protocol) server's tool from the command line.
• When debugging or inspecting the JSON schema of an available MCP tool.
• To execute specific filesystem, database, or API queries provided by a configured MCP server without writing a wrapper script.

When Not to Use

• Inside automated scripts where direct API calls (e.g., curl or language-specific SDKs) are faster and more reliable than shelling out to an MCP server wrapper.
• For managing GitHub resources natively supported by gh (e.g., gh issue list).
• If the required MCP server is not installed or configured in the environment.

Common Pitfalls

• JSON Escaping Errors: Passing complex, nested JSON payloads directly in the command line argument without proper escaping, causing parse errors. (Use stdin or heredocs instead).
• Ignoring Descriptions: Running a tool blindly without first checking its schema and description via mcp-cli <server>/<tool>, leading to incorrect parameter types.
• Assuming Tool Availability: Hardcoding an MCP tool call in a script without verifying that the specific server is actually running and accessible in that environment.

Core Process

1. Discover: mcp-cli → see available servers and tools
2. Explore: mcp-cli <server> → see tools with parameters
3. Inspect: mcp-cli <server>/<tool> → get full JSON input schema
4. Execute: mcp-cli <server>/<tool> '<json>' → run with arguments

Core Principles

• Direct Execution: Favor using mcp-cli commands directly from the shell rather than writing intermediate script wrappers.

Commands / Usage Patterns

Add -d to include descriptions (e.g., mcp-cli filesystem -d)

Quick Start

# List all servers and tool names
mcp-cli

# See all tools with parameters
mcp-cli filesystem

# With descriptions (more verbose)
mcp-cli filesystem -d

# Get JSON schema for specific tool
mcp-cli filesystem/read_file

# Call the tool
mcp-cli filesystem/read_file '{"path": "./README.md"}'

# Search for tools
mcp-cli grep "*file*"

# JSON output for parsing
mcp-cli filesystem/read_file '{"path": "./README.md"}' --json

# Complex JSON with quotes (use heredoc or stdin)
mcp-cli server/tool <<EOF
{"content": "Text with 'quotes' inside"}
EOF

# Or pipe from a file/command
cat args.json | mcp-cli server/tool

# Find all TypeScript files and read the first one
mcp-cli filesystem/search_files '{"path": "src/", "pattern": "*.ts"}' --json | jq -r '.content[0].text' | head -1 | xargs -I {} sh -c 'mcp-cli filesystem/read_file "{\"path\": \"{}\"}"'

Options

Diagnostics and Troubleshooting

Exit Codes:

• 0: Success
• 1: Client error (bad args, missing config)
• 2: Server error (tool failed)
• 3: Network error

Limitations

• Server interactions are isolated to standard streams or network responses depending on the MCP server.

References

• https://github.com/github/awesome-copilot/blob/main/skills/mcp-cli/SKILL.md

Related Skills

• robust-commands: You MUST load this skill when executing commands requiring resilient error recovery or fallbacks.