home / skills / github / awesome-copilot / mcp-cli

mcp-cli skill

Q: What do the exit codes mean?

0 = success; 1 = client error (bad args or missing config); 2 = server error (tool failed); 3 = network error. Check codes in scripts to determine recovery steps.

safe

/skills/mcp-cli

This skill helps you interact with MCP servers via the CLI, listing, exploring, and executing tools to fetch data and automate tasks.

npx playbooks add skill github/awesome-copilot --skill mcp-cli

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: mcp-cli
description: Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line.
---

# MCP-CLI

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

## Commands

| Command                            | Output                          |
| ---------------------------------- | ------------------------------- |
| `mcp-cli`                          | List all servers and tool names |
| `mcp-cli <server>`                 | Show tools with parameters      |
| `mcp-cli <server>/<tool>`          | Get tool JSON schema            |
| `mcp-cli <server>/<tool> '<json>'` | Call tool with arguments        |
| `mcp-cli grep "<glob>"`            | Search tools by name            |

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

## Workflow

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

## Examples

```bash
# 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

| Flag         | Purpose                   |
| ------------ | ------------------------- |
| `-j, --json` | JSON output for scripting |
| `-r, --raw`  | Raw text content          |
| `-d`         | Include descriptions      |

## Exit Codes

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

Overview

This skill provides a command-line interface to MCP (Model Context Protocol) servers so you can discover, inspect, and invoke external tools, APIs, or data sources directly from your shell. It simplifies working with remote capabilities like filesystems, GitHub, databases, and custom APIs via a consistent CLI. Use it to list servers, inspect tool schemas, run tools with JSON inputs, and integrate tool calls into scripts and pipelines.

How this skill works

The CLI queries configured MCP servers to enumerate available servers and tools, prints tool parameter lists, and fetches full JSON input schemas for any tool. You can invoke tools by passing a JSON string or piping JSON via stdin; flags control JSON or raw outputs and verbose descriptions. Exit codes indicate client, server, or network errors, enabling reliable automation and error handling in scripts.

When to use it

Discover available MCP servers and tools from the terminal
Inspect a tool’s JSON input schema before calling it
Execute tool calls with JSON input from scripts or pipelines
Integrate external systems (filesystems, GitHub, databases) into automation
Search tool names or patterns to find relevant capabilities

Best practices

Use mcp-cli to discover tools before calling them to avoid malformed inputs
Prefer --json for machine-readable output when chaining commands or using jq
Use heredoc or stdin for complex JSON with embedded quotes to avoid shell escaping issues
Check exit codes (0,1,2,3) in scripts to handle client, server, and network failures
Use -d to include descriptions when exploring new servers to understand tool purpose

Example use cases

List all servers and tools to map available integrations: mcp-cli
Inspect a filesystem tool schema: mcp-cli filesystem/read_file
Read a file in a script and return JSON for parsing: mcp-cli filesystem/read_file '{"path":"README.md"}' --json
Search for tools that operate on files: mcp-cli grep "*file*"
Chain calls to find TypeScript files and read the first one using jq and xargs

FAQ

How do I pass JSON that contains quotes or newlines?

Supply JSON via heredoc or pipe it through stdin to avoid shell escaping, e.g., mcp-cli server/tool <<EOF ... EOF or cat args.json | mcp-cli server/tool.

What do the exit codes mean?

0 = success; 1 = client error (bad args or missing config); 2 = server error (tool failed); 3 = network error. Check codes in scripts to determine recovery steps.