mcp-cli-tool

Q: How do I install mcp-cli-tool?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill mcp-cli-tool in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mcp-cli-tool/ (personal) or .claude/skills/mcp-cli-tool/ (project).

by reason-machinesAI & Agents

Lightweight CLI for interacting with MCP (Model Context Protocol) servers - discover, inspect, and execute MCP tools from the command line

Installs: 203
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/mcp-skills --skill mcp-cli-tool

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads mcp-cli-tool automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

mcp-cli Tool

Skill by ara.so — MCP Skills collection.

Overview

mcp-cli is a lightweight, Bun-based CLI for interacting with MCP (Model Context Protocol) 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)

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

Manual Install (Requires Bun)

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

Verify Installation

mcp-cli --version

Configuration

Config File Location

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

Path from MCP_CONFIG_PATH environment variable
Path from -c/--config CLI argument
./mcp_servers.json (current directory)
~/.mcp_servers.json
~/.config/mcp/mcp_servers.json

Basic Config Format

Compatible with Claude Desktop, Gemini, and VS Code:

{
  "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

{
  "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:

{
  "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:

{
  "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:

// 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

# 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

# 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

mcp-cli info <server>

Example:

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:

mcp-cli info <server> <tool>
mcp-cli info <server>/<tool>

Example:

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

# 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:

mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}'

Output (JSON):

{
  "content": [
    {
      "type": "text",
      "text": "{\"items\": [{\"name\": \"mcp-cli\", \"url\": \"...\"}]}"
    }
  ]
}

Practical Usage Patterns

1. Discover → Inspect → Execute Workflow

# 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

# 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

# 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

# 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

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

{
  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:

# 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

Environment Variables

Variable	Description	Default
`MCP_CONFIG_PATH`	Path to config file	(none)
`MCP_DEBUG`	Enable debug output	`false`
`MCP_TIMEOUT`	Request timeout (seconds)	`1800`
`MCP_CONCURRENCY`	Servers processed in parallel	`5`
`MCP_MAX_RETRIES`	Retry attempts for transient errors	`3`
`MCP_RETRY_DELAY`	Base retry delay (milliseconds)	`1000`
`MCP_STRICT_ENV`	Error on missing `${VAR}` in config	`true`
`MCP_NO_DAEMON`	Disable connection caching	`false`
`MCP_DAEMON_TIMEOUT`	Idle timeout for cached connections (seconds)	`60`

Example:

# Enable debug mode
export MCP_DEBUG=true
mcp-cli info github

# Use custom config
export MCP_CONFIG_PATH=/path/to/config.json
mcp-cli

# Disable connection pooling
export MCP_NO_DAEMON=true
mcp-cli call server tool '{}'

CLI Options

Option	Description
`-h, --help`	Show help message
`-v, --version`	Show version number
`-d, --with-descriptions`	Include tool descriptions
`-c, --config <path>`	Path to config file

Example:

# List with descriptions
mcp-cli -d

# Use custom config
mcp-cli -c ./my-config.json info github

# Get help
mcp-cli --help

Common MCP Server Setups

Filesystem Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ],
      "allowedTools": ["read_file", "list_directory", "search_files"],
      "disabledTools": ["delete_file"]
    }
  }
}

Usage:

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

GitHub Server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Usage:

mcp-cli call github search_repositories '{"query": "mcp server"}'
mcp-cli call github get_file_contents '{"owner": "user", "repo": "repo", "path": "README.md"}'

HTTP Server

{
  "mcpServers": {
    "api": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Usage:

mcp-cli info api
mcp-cli call api tool_name '{"param": "value"}'

Custom Local Server

{
  "mcpServers": {
    "custom": {
      "command": "node",
      "args": ["./my-server.js"],
      "cwd": "/path/to/project",
      "env": {
        "PORT": "3000",
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Troubleshooting

Config File Not Found

Error:

Error: No MCP configuration found

Solution:

Create mcp_servers.json in current directory or ~/.config/mcp/
Or set MCP_CONFIG_PATH environment variable
Or use -c flag: mcp-cli -c /path/to/config.json

Server Not Starting

Error:

Error: Failed to connect to server 'github'

Solution:

Check command is installed: npx @modelcontextprotocol/server-github --version
Verify environment variables are set
Enable debug mode: MCP_DEBUG=true mcp-cli info github
Check server logs in stderr

Missing Environment Variable

Error:

Error: Environment variable GITHUB_TOKEN not found

Solution:

Set the variable: export GITHUB_TOKEN=your_token
Or use MCP_STRICT_ENV=false to allow empty values (not recommended)

Tool Not Found

Error:

Error: Tool 'invalid_tool' not found on server 'github'

Solution:

List available tools: mcp-cli info github
Check for typos in tool name
Verify tool isn't disabled in config (disabledTools)

Tool Filtered Out

Error:

Error: Tool 'write_file' is disabled by configuration

Solution:

Check config allowedTools and disabledTools
Update config to allow the tool
Remove or modify filtering rules

JSON Parsing Error

Error:

Error: Invalid JSON arguments

Solution:

Use stdin for complex JSON: echo '{}' | mcp-cli call server tool
Escape quotes properly: '{"key": "value"}'
Use heredoc for multi-line JSON

Connection Timeout

Error:

Error: Request timeout after 1800 seconds

Solution:

Increase timeout: export MCP_TIMEOUT=3600
Check server responsiveness
Disable daemon for fresh connection: export MCP_NO_DAEMON=true

Permission Denied

Error:

Error: EACCES: permission denied

Solution:

Check file permissions in cwd directory
Verify user has permission to execute command
For filesystem server, ensure paths are accessible

AI Agent Integration

System Prompt Template

Add this to your AI agent's system prompt:

## MCP Servers

You have access to MCP servers via the `mcp-cli` CLI.

Commands:
- `mcp-cli info` - List all servers
- `mcp-cli info <server>` - Show server tools  
- `mcp-cli info <server> <tool>` - Get tool schema
- `mcp-cli grep "<pattern>"` - Search tools
- `mcp-cli call <server> <tool> '{}'` - Call with JSON args
- `echo '{}' | mcp-cli call <server> <tool>` - Call from stdin

Workflow:
1. Discover: `mcp-cli info` to see available servers
2. Inspect: `mcp-cli info <server> <tool>` to get schema
3. Execute: `mcp-cli call <server> <tool> '{}'` with arguments

Use stdin for complex JSON to avoid shell escaping issues.

Token-Efficient Workflow

Instead of loading all tool schemas:

# ❌ Avoid: Loading everything into context
mcp-cli -d  # Thousands of tokens

# ✅ Efficient: On-demand loading
mcp-cli                               # List servers (minimal tokens)
mcp-cli info github                   # Show tools when needed
mcp-cli info github search_repositories  # Get schema only when calling
mcp-cli call github search_repositories '{"query": "mcp"}'

Script Generation Example

AI can generate shell scripts combining multiple MCP calls:

#!/bin/bash
# Generated by AI agent to analyze repository

# Search for repos
repos=$(mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}')

# Extract URLs
urls=$(echo "$repos" | jq -r '.content[0].text | fromjson | .items[].html_url')

# For each repo, get README
for url in $urls; do
  owner=$(echo "$url" | cut -d'/' -f4)
  repo=$(echo "$url" | cut -d'/' -f5)
  
  echo "=== $owner/$repo ==="
  mcp-cli call github get_file_contents "{\"owner\": \"$owner\", \"repo\": \"$repo\", \"path\": \"README.md\"}" \
    | jq -r '.content[0].text'
done

Best Practices

Use stdin for complex JSON - Avoid shell escaping issues
Enable descriptions sparingly - Use -d only when needed to save tokens
Filter tools in config - Reduce attack surface and simplify discovery
Set environment variables - Use ${VAR} substitution for secrets
Pipe to jq - Process JSON output efficiently
Check schemas first - Use info before call to validate arguments
Handle errors - Check exit codes and stderr in scripts
Use connection pooling - Default daemon keeps connections warm
Search before listing - Use grep for specific tools instead of listing all

FAQ

What does the mcp-cli-tool skill do?

Lightweight CLI for interacting with MCP (Model Context Protocol) servers - discover, inspect, and execute MCP tools from the command line

How do I install mcp-cli-tool?

Run npx skills add https://github.com/reason-machines/mcp-skills --skill mcp-cli-tool in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mcp-cli-tool/ (personal) or .claude/skills/mcp-cli-tool/ (project).

Which AI agents can use mcp-cli-tool?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mcp-cli-tool safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mcp-cli-tool?

It is published by reason-machines in reason-machines/mcp-skills. It has 203 recorded installs.

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs

mcp-cli-tool

Install

Install

Describe the task

Review the result

SKILL.md

mcp-cli Tool

Overview

Installation

Quick Install (Recommended)

Manual Install (Requires Bun)

Verify Installation

Configuration

Config File Location

Basic Config Format

Advanced Config Options

Environment Variable Substitution

Tool Filtering

Core Commands

List All Servers and Tools

Search Tools by Pattern

View Server Details

View Tool Schema

Call a Tool

Practical Usage Patterns

1. Discover → Inspect → Execute Workflow

2. Pipe JSON with jq

3. Chain Multiple MCP Calls

4. Error Handling in Scripts

5. Save Output to File

6. Aggregate Results from Multiple Servers

7. Complex JSON Arguments

Environment Variables

CLI Options

Common MCP Server Setups

Filesystem Server

GitHub Server

HTTP Server

Custom Local Server

Troubleshooting

Config File Not Found

Server Not Starting

Missing Environment Variable

Tool Not Found

Tool Filtered Out

JSON Parsing Error

Connection Timeout

Permission Denied

AI Agent Integration

System Prompt Template

Token-Efficient Workflow

Script Generation Example

Best Practices

FAQ

More from reason-machines/mcp-skills

Popular ai & agents skills