Back to Details

mcp-cli-tool

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

mcp-cli Tool

mcp-cli工具

Skill by ara.so — MCP Skills collection.
由ara.so开发的Skill——MCP Skills集合。

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
mcp-cli
是基于Bun的轻量级CLI工具，用于与MCP（Model Context Protocol）服务器交互。它提供以下功能：
  • 按需加载schema - 仅在需要时获取工具schema，节省AI上下文令牌
  • Shell可组合性 - 输出JSON格式，可与
    jq
    配合使用管道、链式调用和脚本编写
  • 连接池 - 延迟启动的守护进程保持连接活跃（空闲超时时间60秒）
  • 通用支持 - 兼容stdio和HTTP类型的MCP服务器
  • 工具过滤 - 通过配置为每个服务器启用/禁用特定工具
使用场景：
  • AI Agent无需加载完整schema即可访问MCP工具
  • Shell脚本自动化MCP服务器交互
  • 发现和探索可用的MCP功能

Installation

安装

Quick Install (Recommended)

快速安装（推荐）

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

Manual Install (Requires Bun)

手动安装（需要Bun）

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

Verify Installation

验证安装

bash
mcp-cli --version
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
在以下任一位置创建
mcp_servers.json
文件（按顺序查找）：
  1. MCP_CONFIG_PATH
    环境变量指定的路径
  2. -c/--config
    CLI参数指定的路径
  3. ./mcp_servers.json
    （当前目录）
  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"
    }
  }
}
兼容Claude Desktop、Gemini和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}"
      }
    }
  }
}
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
在配置的任意位置使用
${VAR_NAME}
语法：
json
{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}",
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
控制行为：
  • MCP_STRICT_ENV=true
    （默认值）：变量缺失时抛出错误
  • MCP_STRICT_ENV=false
    ：使用空值并发出警告

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"]
使用通配符模式限制可用工具：
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "allowedTools": ["read_file", "list_directory"],
      "disabledTools": ["delete_file"]
    }
  }
}
规则：
  • allowedTools
    ：白名单（支持
    *
    、
    ?
    通配符模式）
  • disabledTools
    ：黑名单（优先级高于白名单）
  • 适用于所有操作（info、grep、call）
示例：
json
// 仅允许读取操作
"allowedTools": ["read_*", "list_*", "search_*"]

// 禁用破坏性操作
"disabledTools": ["delete_*", "write_*", "create_*"]

// 组合过滤器
"allowedTools": ["*file*"],
"disabledTools": ["delete_file"]

Core Commands

核心命令

List All Servers and Tools

列出所有服务器和工具

bash
undefined
bash
undefined

Basic listing

基础列表

mcp-cli
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
undefined
mcp-cli -d

**输出：**
github • search_repositories • get_file_contents • create_or_update_file filesystem • read_file • write_file • list_directory
undefined

Search Tools by Pattern

按模式搜索工具

bash
undefined
bash
undefined

Find file-related tools

查找与文件相关的工具

mcp-cli grep "file"
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
undefined
mcp-cli grep "search" -d

**输出：**
github/get_file_contents github/create_or_update_file filesystem/read_file filesystem/write_file
undefined

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
  ...
bash
mcp-cli info <server>
示例：
bash
mcp-cli info github
输出：
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

查看工具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"]
  }
以下两种格式均可使用：
bash
mcp-cli info <server> <tool>
mcp-cli info <server>/<tool>
示例：
bash
mcp-cli info github search_repositories
输出：
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
undefined
bash
undefined

Inline JSON

内联JSON

mcp-cli call <server> <tool> '{"key": "value"}'
mcp-cli call <server> <tool> '{"key": "value"}'

From stdin (auto-detected, no '-' needed)

从标准输入读取（自动检测，无需'-'）

echo '{"path": "./file"}' | mcp-cli call <server> <tool>
echo '{"path": "./file"}' | mcp-cli call <server> <tool>

Heredoc for complex JSON

使用here文档传递复杂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\": \"...\"}]}"
    }
  ]
}
mcp-cli call <server> <tool> <<EOF {"content": "Text with 'quotes' and "escapes""} EOF

**示例：**
```bash
mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}'
输出（JSON格式）：
json
{
  "content": [
    {
      "type": "text",
      "text": "{\"items\": [{\"name\": \"mcp-cli\", \"url\": \"...\"}]}"
    }
  ]
}

Practical Usage Patterns

实用使用模式

1. Discover → Inspect → Execute Workflow

1. 发现 → 查看 → 执行工作流

bash
undefined
bash
undefined

Step 1: List available servers

步骤1：列出可用服务器

mcp-cli
mcp-cli

Step 2: View server tools

步骤2：查看服务器工具

mcp-cli info filesystem
mcp-cli info filesystem

Step 3: Get tool schema

步骤3：获取工具schema

mcp-cli info filesystem read_file
mcp-cli info filesystem read_file

Step 4: Call the tool

步骤4：调用工具

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

2. Pipe JSON with jq

2. 使用jq处理JSON管道

bash
undefined
bash
undefined

Extract specific field

提取特定字段

mcp-cli call github search_repositories '{"query": "mcp"}' | jq '.content[0].text'
mcp-cli call github search_repositories '{"query": "mcp"}' | jq '.content[0].text'

Parse nested JSON

解析嵌套JSON

mcp-cli call github search_repositories '{"query": "mcp"}'
| jq -r '.content[0].text | fromjson | .items[].html_url'
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"))'
undefined
mcp-cli call filesystem list_directory '{"path": "."}'
| jq -r '.content[0].text | split("\n")[] | select(endswith(".md"))'
undefined

3. Chain Multiple MCP Calls

3. 链式调用多个MCP命令

bash
undefined
bash
undefined

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": "{}"}'
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
undefined
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
undefined

4. Error Handling in Scripts

4. 脚本中的错误处理

bash
undefined
bash
undefined

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"}'
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
undefined
if result=$(mcp-cli call filesystem read_file '{"path": "./config.json"}' 2>/dev/null); then echo "$result" | jq '.content[0].text | fromjson' else echo "文件未找到，使用默认配置" fi
undefined

5. Save Output to File

5. 将输出保存到文件

bash
mcp-cli call github get_file_contents '{"owner": "user", "repo": "project", "path": "src/main.ts"}' \
  | jq -r '.content[0].text' > main.ts
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

6. 聚合多个服务器的结果

bash
{
  mcp-cli call github search_repositories '{"query": "mcp", "per_page": 3}'
  mcp-cli call filesystem list_directory '{"path": "./src"}'
} | jq -s '.'
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

7. 复杂JSON参数

For JSON with special characters, use stdin to avoid shell escaping:
bash
undefined
对于包含特殊字符的JSON，使用标准输入避免Shell转义问题：
bash
undefined

Heredoc (recommended)

Here文档（推荐）

mcp-cli call server tool <<EOF { "content": "Text with 'single quotes' and "double quotes"", "metadata": { "nested": "value" } } EOF
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
cat args.json | mcp-cli call server tool

Using jq to build complex JSON

使用jq构建复杂JSON

jq -n '{query: "mcp", filters: ["active", "starred"]}' | mcp-cli call github search
undefined
jq -n '{query: "mcp", filters: ["active", "starred"]}' | mcp-cli call github search
undefined

Environment Variables

环境变量

VariableDescriptionDefault
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:
bash
undefined
变量名描述默认值
MCP_CONFIG_PATH
配置文件路径无
MCP_DEBUG
启用调试输出
false
MCP_TIMEOUT
请求超时时间（秒）
1800
MCP_CONCURRENCY
并行处理的服务器数量
5
MCP_MAX_RETRIES
临时错误的重试次数
3
MCP_RETRY_DELAY
基础重试延迟（毫秒）
1000
MCP_STRICT_ENV
配置中缺失
${VAR}
时抛出错误
true
MCP_NO_DAEMON
禁用连接缓存
false
MCP_DAEMON_TIMEOUT
缓存连接的空闲超时时间（秒）
60
示例：
bash
undefined

Enable debug mode

启用调试模式

export MCP_DEBUG=true mcp-cli info github
export MCP_DEBUG=true mcp-cli info github

Use custom config

使用自定义配置

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

Disable connection pooling

禁用连接池

export MCP_NO_DAEMON=true mcp-cli call server tool '{}'
undefined
export MCP_NO_DAEMON=true mcp-cli call server tool '{}'
undefined

CLI Options

CLI选项

OptionDescription
-h, --help
Show help message
-v, --version
Show version number
-d, --with-descriptions
Include tool descriptions
-c, --config <path>
Path to config file
Example:
bash
undefined
选项描述
-h, --help
显示帮助信息
-v, --version
显示版本号
-d, --with-descriptions
包含工具描述
-c, --config <path>
指定配置文件路径
示例：
bash
undefined

List with descriptions

列出工具并显示描述

mcp-cli -d
mcp-cli -d

Use custom config

使用自定义配置

mcp-cli -c ./my-config.json info github
mcp-cli -c ./my-config.json info github

Get help

获取帮助

mcp-cli --help
undefined
mcp-cli --help
undefined

Common MCP Server Setups

常见MCP服务器配置

Filesystem Server

文件系统服务器

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ],
      "allowedTools": ["read_file", "list_directory", "search_files"],
      "disabledTools": ["delete_file"]
    }
  }
}
Usage:
bash
mcp-cli call filesystem read_file '{"path": "./README.md"}'
mcp-cli call filesystem list_directory '{"path": "."}'
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ],
      "allowedTools": ["read_file", "list_directory", "search_files"],
      "disabledTools": ["delete_file"]
    }
  }
}
用法：
bash
mcp-cli call filesystem read_file '{"path": "./README.md"}'
mcp-cli call filesystem list_directory '{"path": "."}'

GitHub Server

GitHub服务器

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
Usage:
bash
mcp-cli call github search_repositories '{"query": "mcp server"}'
mcp-cli call github get_file_contents '{"owner": "user", "repo": "repo", "path": "README.md"}'
json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
用法：
bash
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

HTTP服务器

json
{
  "mcpServers": {
    "api": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
Usage:
bash
mcp-cli info api
mcp-cli call api tool_name '{"param": "value"}'
json
{
  "mcpServers": {
    "api": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
用法：
bash
mcp-cli info api
mcp-cli call api tool_name '{"param": "value"}'

Custom Local Server

自定义本地服务器

json
{
  "mcpServers": {
    "custom": {
      "command": "node",
      "args": ["./my-server.js"],
      "cwd": "/path/to/project",
      "env": {
        "PORT": "3000",
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
json
{
  "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:
  1. Create 
    mcp_servers.json
    in current directory or 
    ~/.config/mcp/
  2. Or set 
    MCP_CONFIG_PATH
    environment variable
  3. Or use 
    -c
    flag: 
    mcp-cli -c /path/to/config.json
错误：
Error: No MCP configuration found
解决方案：
  1. 在当前目录或
    ~/.config/mcp/
    下创建
    mcp_servers.json
    文件
  2. 或者设置
    MCP_CONFIG_PATH
    环境变量
  3. 或者使用
    -c
    参数：
    mcp-cli -c /path/to/config.json

Server Not Starting

服务器无法启动

Error:
Error: Failed to connect to server 'github'
Solution:
  1. Check command is installed: 
    npx @modelcontextprotocol/server-github --version
  2. Verify environment variables are set
  3. Enable debug mode: 
    MCP_DEBUG=true mcp-cli info github
  4. Check server logs in stderr
错误：
Error: Failed to connect to server 'github'
解决方案：
  1. 检查命令是否已安装：
    npx @modelcontextprotocol/server-github --version
  2. 验证环境变量是否已设置
  3. 启用调试模式：
    MCP_DEBUG=true mcp-cli info github
  4. 在stderr中查看服务器日志

Missing Environment Variable

缺失环境变量

Error:
Error: Environment variable GITHUB_TOKEN not found
Solution:
  1. Set the variable: 
    export GITHUB_TOKEN=your_token
  2. Or use 
    MCP_STRICT_ENV=false
    to allow empty values (not recommended)
错误：
Error: Environment variable GITHUB_TOKEN not found
解决方案：
  1. 设置变量：
    export GITHUB_TOKEN=your_token
  2. 或者设置
    MCP_STRICT_ENV=false
    允许空值（不推荐）

Tool Not Found

未找到工具

Error:
Error: Tool 'invalid_tool' not found on server 'github'
Solution:
  1. List available tools: 
    mcp-cli info github
  2. Check for typos in tool name
  3. Verify tool isn't disabled in config (
    disabledTools
    )
错误：
Error: Tool 'invalid_tool' not found on server 'github'
解决方案：
  1. 列出可用工具：
    mcp-cli info github
  2. 检查工具名称是否有拼写错误
  3. 验证工具是否未在配置中被禁用（
    disabledTools
    ）

Tool Filtered Out

工具被过滤

Error:
Error: Tool 'write_file' is disabled by configuration
Solution:
  1. Check config 
    allowedTools
    and 
    disabledTools
  2. Update config to allow the tool
  3. Remove or modify filtering rules
错误：
Error: Tool 'write_file' is disabled by configuration
解决方案：
  1. 检查配置中的
    allowedTools
    和
    disabledTools
  2. 更新配置以启用该工具
  3. 删除或修改过滤规则

JSON Parsing Error

JSON解析错误

Error:
Error: Invalid JSON arguments
Solution:
  1. Use stdin for complex JSON: 
    echo '{}' | mcp-cli call server tool
  2. Escape quotes properly: 
    '{"key": "value"}'
  3. Use heredoc for multi-line JSON
错误：
Error: Invalid JSON arguments
解决方案：
  1. 对复杂JSON使用标准输入：
    echo '{}' | mcp-cli call server tool
  2. 正确转义引号：
    '{"key": "value"}'
  3. 对多行JSON使用here文档

Connection Timeout

连接超时

Error:
Error: Request timeout after 1800 seconds
Solution:
  1. Increase timeout: 
    export MCP_TIMEOUT=3600
  2. Check server responsiveness
  3. Disable daemon for fresh connection: 
    export MCP_NO_DAEMON=true
错误：
Error: Request timeout after 1800 seconds
解决方案：
  1. 增加超时时间：
    export MCP_TIMEOUT=3600
  2. 检查服务器响应情况
  3. 禁用守护进程以建立新连接：
    export MCP_NO_DAEMON=true

Permission Denied

权限拒绝

Error:
Error: EACCES: permission denied
Solution:
  1. Check file permissions in 
    cwd
    directory
  2. Verify user has permission to execute command
  3. For filesystem server, ensure paths are accessible
错误：
Error: EACCES: permission denied
解决方案：
  1. 检查
    cwd
    目录下的文件权限
  2. 验证用户是否有执行命令的权限
  3. 对于文件系统服务器，确保路径可访问

AI Agent Integration

AI Agent集成

System Prompt Template

系统提示词模板

Add this to your AI agent's system prompt:
markdown
undefined
将以下内容添加到AI Agent的系统提示词中：
markdown
undefined

MCP Servers

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.
undefined
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.
undefined

Token-Efficient Workflow

令牌高效工作流

Instead of loading all tool schemas:
bash
undefined
无需加载所有工具schema：
bash
undefined

❌ Avoid: Loading everything into context

❌ 避免：将所有内容加载到上下文

mcp-cli -d # Thousands of tokens
mcp-cli -d # 数千个令牌

✅ 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"}'
undefined
mcp-cli # 列出服务器（最少令牌） mcp-cli info github # 需要时查看工具 mcp-cli info github search_repositories # 调用时才获取schema mcp-cli call github search_repositories '{"query": "mcp"}'
undefined

Script Generation Example

脚本生成示例

AI can generate shell scripts combining multiple MCP calls:
bash
#!/bin/bash
AI可以生成组合多个MCP调用的Shell脚本：
bash
#!/bin/bash

Generated by AI agent to analyze repository

Generated by AI agent to analyze repository

Search for repos

Search for repos

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

Extract URLs

Extract URLs

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

For each repo, get README

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

Best Practices

最佳实践

  1. Use stdin for complex JSON - Avoid shell escaping issues
  2. Enable descriptions sparingly - Use 
    -d
    only when needed to save tokens
  3. Filter tools in config - Reduce attack surface and simplify discovery
  4. Set environment variables - Use 
    ${VAR}
    substitution for secrets
  5. Pipe to jq - Process JSON output efficiently
  6. Check schemas first - Use 
    info
    before 
    call
    to validate arguments
  7. Handle errors - Check exit codes and stderr in scripts
  8. Use connection pooling - Default daemon keeps connections warm
  9. Search before listing - Use 
    grep
    for specific tools instead of listing all
  1. 对复杂JSON使用标准输入 - 避免Shell转义问题
  2. 谨慎启用描述 - 仅在需要时使用
    -d
    参数以节省令牌
  3. 在配置中过滤工具 - 减少攻击面并简化发现过程
  4. 设置环境变量 - 使用
    ${VAR}
    替换敏感信息
  5. 使用jq处理管道输出 - 高效处理JSON输出
  6. 先检查schema - 在调用
    call
    之前使用
    info
    验证参数
  7. 处理错误 - 在脚本中检查退出码和stderr
  8. 使用连接池 - 默认守护进程保持连接活跃
  9. 先搜索再列出 - 使用
    grep
    查找特定工具，而非列出所有工具