mcpField
M
mcp-cli

mcp-cli

github.com/philschmidAgent workflows1.3k412 installsUpdated 38w ago
Repository

About mcp-cli

mcp-cli is a command-line client for discovering MCP servers and tools, inspecting tool parameters and schemas, and invoking tools. It also supports shell-based chaining and reports distinct exit codes for client, server, and network errors.

Key features

  1. 01List configured servers and tools
  2. 02Inspect tool parameters and JSON schemas
  3. 03Search tools by name
  4. 04Call tools with arguments or stdin JSON
  5. 05Chain calls in shell workflows

Use cases

  1. 01Find an available MCP tool
  2. 02Check a tool schema before calling it
  3. 03Run a tool with JSON input
  4. 04Pipe one tool's output into another call

MCP support

The CLI connects to configured MCP servers to discover and inspect their tools, then invokes those tools with supplied arguments.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/philschmid/mcp-cli --skill mcp-cli

After installing, type/mcp-cliin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

install.sh
README.md
biome.json
LICENSE
CHANGELOG.md
.gitignore
bun.lock
mcp_servers.json
package.json
.github/workflows/
release.yml
ci.yml
scripts/
release.sh
generate-system-instructions.ts
src/
client.ts
config.ts
daemon-client.ts
daemon.ts
errors.ts
index.ts
output.ts
version.ts
src/commands/
grep.ts
call.ts
info.ts
list.ts
tests/
cli-errors.test.ts
client.test.ts
config.test.ts
filter.test.ts
errors.test.ts

Details

From the project README

MCP-CLI

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

Commands

CommandOutput
mcp-cliList all servers and tools
mcp-cli info <server>Show server tools and parameters
mcp-cli info <server> <tool>Get tool JSON schema
mcp-cli grep "<pattern>"Search tools by name
mcp-cli call <server> <tool>Call tool (reads JSON from stdin if no args)
mcp-cli call <server> <tool> '<json>'Call tool with arguments

Both formats work: <server> <tool> or <server>/<tool>

Workflow

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

Examples

# List all servers
mcp-cli

# With descriptions  
mcp-cli -d

# See server tools
mcp-cli info filesystem

# Get tool schema (both formats work)
mcp-cli info filesystem read_file
mcp-cli info filesystem/read_file

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

# Pipe from stdin (no '-' needed!)
cat args.json | mcp-cli call filesystem read_file

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

# Output is raw text (pipe-friendly)
mcp-cli call filesystem read_file '{"path": "./file"}' | head -10

Advanced Chaining

# Chain: search files → read first match
mcp-cli call filesystem search_files '{"path": ".", "pattern": "*.md"}' \
  | head -1 \
  | xargs -I {} mcp-cli call filesystem read_file '{"path": "{}"}'

# Loop: process multiple files
mcp-cli call filesystem list_directory '{"path": "./src"}' \
  | while read f; do mcp-cli call filesystem read_file "{\"path\": \"$f\"}"; done

# Conditional: check before reading
mcp-cli call filesystem list_directory '{"path": "."}' \
  | grep -q "README" \
  && mcp-cli call filesystem read_file '{"path": "./README.md"}'

# Multi-server aggregation
{
  mcp-cli call github search_repositories '{"query": "mcp", "per_page": 3}'
  mcp-cli call filesystem list_directory '{"path": "."}'
}

# Save to file
mcp-cli call github get_file_contents '{"owner": "x", "repo": "y", "path": "z"}' > output.txt

Note: call outputs raw text content directly (no jq needed for text extraction)

Options

FlagPurpose
-dInclude descriptions
-c <path>Specify config file

Common Errors

Wrong CommandErrorFix
mcp-cli server toolAMBIGUOUS_COMMANDUse call server tool or info server tool
mcp-cli run server toolUNKNOWN_SUBCOMMANDUse call instead of run
mcp-cli listUNKNOWN_SUBCOMMANDUse info instead of list
mcp-cli call serverMISSING_ARGUMENTAdd tool name
mcp-cli call server tool {bad}INVALID_JSONUse valid JSON with quotes

Exit Codes

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

Comments

Markdown supported