mcp-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP CLI: On-Demand MCP Server Usage

MCP CLI：按需使用MCP服务器

Use the

mcp

CLI tool to dynamically discover and invoke MCP server capabilities without pre-configuring them as permanent integrations.

使用

mcp

CLI工具动态发现并调用MCP服务器的功能，无需将它们预配置为永久集成。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Explore an MCP server's capabilities before deciding to use it
Make one-off calls to an MCP server without permanent integration
Access MCP functionality without polluting the context window
Test or debug MCP servers
Use MCP servers that aren't pre-configured

在以下场景中使用本技能：

在决定使用某MCP服务器前，探索其功能
对MCP服务器进行一次性调用，无需永久集成
访问MCP功能，且不占用上下文窗口
测试或调试MCP服务器
使用未预配置的MCP服务器

Prerequisites

前提条件

The

mcp

CLI must be installed at

~/.local/bin/mcp

. If not present:

bash

undefined

mcp

CLI必须安装在

~/.local/bin/mcp

路径下。如果未安装：

bash

undefined

Clone and build

cd /tmp && git clone --depth 1 https://github.com/f/mcptools.git cd mcptools && CGO_ENABLED=0 go build -o ~/.local/bin/mcp ./cmd/mcptools


Always ensure PATH includes the binary:
```bash
export PATH="$HOME/.local/bin:$PATH"

cd /tmp && git clone --depth 1 https://github.com/f/mcptools.git cd mcptools && CGO_ENABLED=0 go build -o ~/.local/bin/mcp ./cmd/mcptools


请确保PATH环境变量包含该二进制文件：
```bash
export PATH="$HOME/.local/bin:$PATH"

Discovery Workflow

发现工作流

Step 1: Discover Available Tools

步骤1：发现可用工具

bash

mcp tools <server-command>

Examples:

bash

undefined

bash

mcp tools <server-command>

示例：

bash

undefined

Filesystem server

mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow

Memory/knowledge graph server

mcp tools npx -y @modelcontextprotocol/server-memory

GitHub server (requires token)

mcp tools docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

HTTP-based server

mcp tools https://example.com/mcp

undefined

mcp tools https://example.com/mcp

undefined

Step 2: Discover Resources (if supported)

步骤2：发现资源（如支持）

bash

mcp resources <server-command>

Resources are data sources the server exposes (files, database entries, etc.).

bash

mcp resources <server-command>

资源指服务器暴露的数据源（如文件、数据库条目等）。

Step 3: Discover Prompts (if supported)

步骤3：发现提示模板（如支持）

bash

mcp prompts <server-command>

Prompts are pre-defined prompt templates the server provides.

bash

mcp prompts <server-command>

提示模板指服务器提供的预定义提示模板。

Step 4: Get Detailed Info (JSON format)

步骤4：获取详细信息（JSON格式）

bash

undefined

bash

undefined

For full schema details including parameter types

获取包含参数类型的完整架构详情

mcp tools --format json <server-command> mcp tools --format pretty <server-command>

undefined

mcp tools --format json <server-command> mcp tools --format pretty <server-command>

undefined

Making Tool Calls

调用工具

Basic Syntax

基本语法

bash

mcp call <tool_name> --params '<json>' <server-command>

bash

mcp call <tool_name> --params '<json>' <server-command>

Examples

示例

Read a file:

bash

mcp call read_file --params '{"path": "/tmp/example.txt"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Write a file:

bash

mcp call write_file --params '{"path": "/tmp/test.txt", "content": "Hello world"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

List directory:

bash

mcp call list_directory --params '{"path": "/tmp"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Create entities (memory server):

bash

mcp call create_entities --params '{"entities": [{"name": "Project", "entityType": "Software", "observations": ["Uses TypeScript"]}]}' \
  npx -y @modelcontextprotocol/server-memory

Search (memory server):

bash

mcp call search_nodes --params '{"query": "TypeScript"}' \
  npx -y @modelcontextprotocol/server-memory

读取文件：

bash

mcp call read_file --params '{"path": "/tmp/example.txt"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

写入文件：

bash

mcp call write_file --params '{"path": "/tmp/test.txt", "content": "Hello world"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

列出目录：

bash

mcp call list_directory --params '{"path": "/tmp"}' \
  npx -y @modelcontextprotocol/server-filesystem /tmp

创建实体（内存服务器）：

bash

mcp call create_entities --params '{"entities": [{"name": "Project", "entityType": "Software", "observations": ["Uses TypeScript"]}]}' \
  npx -y @modelcontextprotocol/server-memory

搜索（内存服务器）：

bash

mcp call search_nodes --params '{"query": "TypeScript"}' \
  npx -y @modelcontextprotocol/server-memory

Complex Parameters

复杂参数

For nested objects and arrays, ensure valid JSON:

bash

mcp call edit_file --params '{
  "path": "/tmp/file.txt",
  "edits": [
    {"oldText": "foo", "newText": "bar"},
    {"oldText": "baz", "newText": "qux"}
  ]
}' npx -y @modelcontextprotocol/server-filesystem /tmp

对于嵌套对象和数组，请确保使用有效的JSON格式：

bash

mcp call edit_file --params '{
  "path": "/tmp/file.txt",
  "edits": [
    {"oldText": "foo", "newText": "bar"},
    {"oldText": "baz", "newText": "qux"}
  ]
}' npx -y @modelcontextprotocol/server-filesystem /tmp

Output Formats

输出格式

bash

undefined

bash

undefined

Table (default, human-readable)

表格格式（默认，易读）

mcp call <tool> --params '{}' <server>

JSON (for parsing)

JSON格式（用于解析）

mcp call <tool> --params '{}' -f json <server>

Pretty JSON (readable JSON)

美化JSON格式（易读的JSON）

mcp call <tool> --params '{}' -f pretty <server>

undefined

mcp call <tool> --params '{}' -f pretty <server>

undefined

Reading Resources

读取资源

bash

undefined

bash

undefined

List available resources

列出可用资源

mcp resources <server-command>

Read a specific resource

读取特定资源

mcp read-resource <resource-uri> <server-command>

Alternative syntax

替代语法

mcp call resource:<resource-uri> <server-command>

undefined

mcp call resource:<resource-uri> <server-command>

undefined

Using Prompts

使用提示模板

bash

undefined

bash

undefined

List available prompts

列出可用提示模板

mcp prompts <server-command>

Get a prompt (may require arguments)

获取提示模板（可能需要参数）

mcp get-prompt <prompt-name> <server-command>

With parameters

带参数使用

mcp get-prompt <prompt-name> --params '{"arg": "value"}' <server-command>

undefined

mcp get-prompt <prompt-name> --params '{"arg": "value"}' <server-command>

undefined

Server Aliases (for repeated use)

服务器别名（重复使用时）

If using a server frequently during a session:

bash

undefined

如果在会话中频繁使用某服务器：

bash

undefined

Create alias

创建别名

mcp alias add fs npx -y @modelcontextprotocol/server-filesystem /home/user

Use alias

使用别名

mcp tools fs mcp call read_file --params '{"path": "README.md"}' fs

List aliases

列出别名

mcp alias list

Remove when done

使用完成后删除

mcp alias remove fs


Aliases are stored in `~/.mcpt/aliases.json`.

mcp alias remove fs


别名存储在`~/.mcpt/aliases.json`文件中。

Authentication

身份验证

HTTP Basic Auth

HTTP基础认证

bash

mcp tools --auth-user "username:password" https://api.example.com/mcp

bash

mcp tools --auth-user "username:password" https://api.example.com/mcp

Bearer Token

Bearer令牌

bash

mcp tools --auth-header "Bearer your-token-here" https://api.example.com/mcp

bash

mcp tools --auth-header "Bearer your-token-here" https://api.example.com/mcp

Environment Variables (for Docker-based servers)

环境变量（适用于基于Docker的服务器）

bash

mcp tools docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_TOKEN" \
  ghcr.io/github/github-mcp-server

bash

mcp tools docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_TOKEN" \
  ghcr.io/github/github-mcp-server

Transport Types

传输类型

Stdio (default for npx/node commands)

Stdio（npx/node命令默认使用）

bash

mcp tools npx -y @modelcontextprotocol/server-filesystem /tmp

bash

mcp tools npx -y @modelcontextprotocol/server-filesystem /tmp

HTTP (auto-detected for http/https URLs)

HTTP（自动检测http/https URL）

bash

mcp tools https://example.com/mcp

bash

mcp tools https://example.com/mcp

SSE (Server-Sent Events)

SSE（服务器发送事件）

bash

mcp tools http://localhost:3001/sse

bash

mcp tools http://localhost:3001/sse

Or explicitly:

或显式指定：

mcp tools --transport sse http://localhost:3001

undefined

mcp tools --transport sse http://localhost:3001

undefined

Common MCP Servers

常见MCP服务器

Filesystem

文件系统

bash

undefined

bash

undefined

Allow access to specific directory

允许访问特定目录

mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow

undefined

mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow

undefined

Memory (Knowledge Graph)

内存（知识图谱）

bash

mcp tools npx -y @modelcontextprotocol/server-memory

bash

mcp tools npx -y @modelcontextprotocol/server-memory

GitHub

bash

export GITHUB_PERSONAL_ACCESS_TOKEN="your-token"
mcp tools docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

bash

export GITHUB_PERSONAL_ACCESS_TOKEN="your-token"
mcp tools docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Brave Search

Brave搜索

bash

export BRAVE_API_KEY="your-key"
mcp tools npx -y @anthropic/mcp-server-brave-search

bash

export BRAVE_API_KEY="your-key"
mcp tools npx -y @anthropic/mcp-server-brave-search

Puppeteer (Browser Automation)

Puppeteer（浏览器自动化）

bash

mcp tools npx -y @anthropic/mcp-server-puppeteer

bash

mcp tools npx -y @anthropic/mcp-server-puppeteer

Best Practices

最佳实践

1. Always Discover First

1. 始终先发现

Before calling tools, run

mcp tools

to understand what's available and the exact parameter schema.

在调用工具前，运行

mcp tools

命令了解可用功能和确切的参数架构。

2. Use JSON Format for Parsing

2. 使用JSON格式进行解析

When you need to process results programmatically:

bash

mcp call <tool> --params '{}' -f json <server> | jq '.field'

当需要以编程方式处理结果时：

bash

mcp call <tool> --params '{}' -f json <server> | jq '.field'

3. Validate Parameters

3. 验证参数

The table output shows parameter signatures. Match them exactly:

```
param:str
```
= string
```
param:num
```
= number
```
param:bool
```
= boolean
```
param:str[]
```
= array of strings
```
[param:str]
```
= optional parameter

表格输出会显示参数签名，请严格匹配：

```
param:str
```
= 字符串
```
param:num
```
= 数字
```
param:bool
```
= 布尔值
```
param:str[]
```
= 字符串数组
```
[param:str]
```
= 可选参数

4. Handle Errors Gracefully

4. 优雅处理错误

Tool calls may fail. Check exit codes and stderr:

bash

if ! result=$(mcp call tool --params '{}' server 2>&1); then
  echo "Error: $result"
fi

工具调用可能失败，请检查退出码和标准错误输出：

bash

if ! result=$(mcp call tool --params '{}' server 2>&1); then
  echo "Error: $result"
fi

5. Use Aliases for Multi-Step Operations

5. 对多步骤操作使用别名

If making several calls to the same server:

bash

mcp alias add tmp-server npx -y @modelcontextprotocol/server-filesystem /tmp
mcp call list_directory --params '{"path": "/tmp"}' tmp-server
mcp call read_file --params '{"path": "/tmp/file.txt"}' tmp-server
mcp alias remove tmp-server

如果需要对同一服务器进行多次调用：

bash

mcp alias add tmp-server npx -y @modelcontextprotocol/server-filesystem /tmp
mcp call list_directory --params '{"path": "/tmp"}' tmp-server
mcp call read_file --params '{"path": "/tmp/file.txt"}' tmp-server
mcp alias remove tmp-server

6. Restrict Capabilities with Guard

6. 使用Guard限制功能

For safety, limit what tools are accessible:

bash

undefined

为安全起见，限制可访问的工具：

bash

undefined

Only allow read operations

仅允许读取操作

mcp guard --allow 'tools:read_,list_' --deny 'tools:write_,delete_'
npx -y @modelcontextprotocol/server-filesystem /home

undefined

mcp guard --allow 'tools:read_,list_' --deny 'tools:write_,delete_'
npx -y @modelcontextprotocol/server-filesystem /home

undefined

Debugging

调试

View Server Logs

查看服务器日志

bash

mcp tools --server-logs <server-command>

bash

mcp tools --server-logs <server-command>

Check Alias Configuration

检查别名配置

bash

cat ~/.mcpt/aliases.json

bash

cat ~/.mcpt/aliases.json

Verbose Output

详细输出

Use

--format pretty

for detailed JSON output to debug parameter issues.

使用

--format pretty

获取详细的JSON输出，以调试参数问题。

Quick Reference

快速参考

Action	Command
List tools	`mcp tools <server>`
List resources	`mcp resources <server>`
List prompts	`mcp prompts <server>`
Call tool	`mcp call <tool> --params '<json>' <server>`
Read resource	`mcp read-resource <uri> <server>`
Get prompt	`mcp get-prompt <name> <server>`
Add alias	`mcp alias add <name> <server-command>`
Remove alias	`mcp alias remove <name>`
JSON output	Add `-f json` or `-f pretty`

操作	命令
列出工具	`mcp tools <server>`
列出资源	`mcp resources <server>`
列出提示模板	`mcp prompts <server>`
调用工具	`mcp call <tool> --params '<json>' <server>`
读取资源	`mcp read-resource <uri> <server>`
获取提示模板	`mcp get-prompt <name> <server>`
添加别名	`mcp alias add <name> <server-command>`
删除别名	`mcp alias remove <name>`
JSON输出	添加 `-f json` 或 `-f pretty`

Example: Complete Workflow

示例：完整工作流

bash

undefined

bash

undefined

1. Discover what's available

1. 发现可用功能

mcp tools npx -y @modelcontextprotocol/server-filesystem /home/user/project

2. Check for resources

2. 检查资源

mcp resources npx -y @modelcontextprotocol/server-filesystem /home/user/project

3. Create alias for convenience

3. 创建别名以方便使用

mcp alias add proj npx -y @modelcontextprotocol/server-filesystem /home/user/project

4. Explore directory structure

4. 探索目录结构

mcp call directory_tree --params '{"path": "/home/user/project"}' proj

5. Read specific files

5. 读取特定文件

mcp call read_file --params '{"path": "/home/user/project/README.md"}' proj

6. Search for patterns

6. 搜索模式

mcp call search_files --params '{"path": "/home/user/project", "pattern": "**/*.ts"}' proj

7. Clean up alias

7. 清理别名

mcp alias remove proj

undefined

mcp alias remove proj

undefined

Troubleshooting

故障排除

"command not found: mcp"

Ensure PATH is set:

export PATH="$HOME/.local/bin:$PATH"

确保已设置PATH环境变量：

export PATH="$HOME/.local/bin:$PATH"

JSON parse errors

JSON解析错误

Escape special characters properly
Avoid shell expansion issues by using single quotes around JSON
For complex JSON, write to a temp file and use
```
--params "$(cat params.json)"
```

正确转义特殊字符
使用单引号包裹JSON，避免shell扩展问题
对于复杂JSON，可将其写入临时文件，然后使用
```
--params "$(cat params.json)"
```

Server timeout

服务器超时

Some servers take time to start. The mcp CLI waits for initialization automatically.

部分服务器启动需要时间，mcp CLI会自动等待初始化完成。

Permission denied

权限被拒绝

For filesystem server, ensure the allowed directory path is correct and accessible.

对于文件系统服务器，请确保允许访问的目录路径正确且可访问。