MCP CLI 使用指南：动态调用 MCP 服务器工具，无需永久集成

mcp-cli by obra/superpowers-lab

135 周安装量

268 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/obra/superpowers-lab --skill mcp-cli

AI/机器学习开发命令行工具

🇨🇳中文介绍

MCP CLI：按需使用 MCP 服务器

使用 mcp CLI 工具动态发现和调用 MCP 服务器功能，无需预先将其配置为永久集成。

何时使用此技能

在以下情况下使用此技能：

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

先决条件

mcp CLI 必须安装在 ~/.local/bin/mcp。如果不存在：

# 克隆并构建
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 包含该二进制文件：

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

发现工作流程

步骤 1：发现可用工具

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

mcp resources <server-command>

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

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

mcp prompts <server-command>

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

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

# 获取完整的模式详细信息，包括参数类型
mcp tools --format json <server-command>
mcp tools --format pretty <server-command>

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

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

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

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

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

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

搜索（内存服务器）：

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

对于嵌套对象和数组，确保 JSON 有效：

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

# 表格（默认，人类可读）
mcp call <tool> --params '{}' <server>

# JSON（用于解析）
mcp call <tool> --params '{}' -f json <server>

# 美化 JSON（可读的 JSON）
mcp call <tool> --params '{}' -f pretty <server>

# 列出可用资源
mcp resources <server-command>

# 读取特定资源
mcp read-resource <resource-uri> <server-command>

# 替代语法
mcp call resource:<resource-uri> <server-command>

# 列出可用提示
mcp prompts <server-command>

# 获取提示（可能需要参数）
mcp get-prompt <prompt-name> <server-command>

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

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

如果在会话期间频繁使用某个服务器：

# 创建别名
mcp alias add fs npx -y @modelcontextprotocol/server-filesystem /home/user

# 使用别名
mcp tools fs
mcp call read_file --params '{"path": "README.md"}' fs

# 列出别名
mcp alias list

# 完成后移除
mcp alias remove fs

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

HTTP 基本身份验证

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

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

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

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

Stdio（npx/node 命令的默认值）

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

HTTP（对 http/https URL 自动检测）

mcp tools https://example.com/mcp

SSE（服务器发送事件）

mcp tools http://localhost:3001/sse
# 或显式指定：
mcp tools --transport sse http://localhost:3001

常见 MCP 服务器

# 允许访问特定目录
mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow

内存（知识图谱）

mcp tools npx -y @modelcontextprotocol/server-memory

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

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

Puppeteer（浏览器自动化）

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

1. 始终先进行发现

在调用工具之前，运行 mcp tools 以了解可用的内容以及确切的参数模式。

2. 使用 JSON 格式进行解析

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

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

表格输出显示参数签名。请精确匹配：

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

4. 优雅地处理错误

工具调用可能失败。检查退出代码和 stderr：

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

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

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

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. 使用 Guard 限制功能

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

# 仅允许读取操作
mcp guard --allow 'tools:read_*,list_*' --deny 'tools:write_*,delete_*' \
  npx -y @modelcontextprotocol/server-filesystem /home

查看服务器日志

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

cat ~/.mcpt/aliases.json

使用 --format pretty 获取详细的 JSON 输出以调试参数问题。

操作	命令
列出工具	`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`

示例：完整工作流程

# 1. 发现可用的内容
mcp tools npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 2. 检查资源
mcp resources npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 3. 为方便起见创建别名
mcp alias add proj npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 4. 探索目录结构
mcp call directory_tree --params '{"path": "/home/user/project"}' proj

# 5. 读取特定文件
mcp call read_file --params '{"path": "/home/user/project/README.md"}' proj

# 6. 搜索模式
mcp call search_files --params '{"path": "/home/user/project", "pattern": "**/*.ts"}' proj

# 7. 清理别名
mcp alias remove proj

"command not found: mcp"

确保 PATH 已设置：export PATH="$HOME/.local/bin:$PATH"

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

某些服务器需要时间启动。mcp CLI 会自动等待初始化。

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

2026 年 1 月 21 日

🇺🇸English

MCP CLI: On-Demand MCP Server Usage

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

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

Prerequisites

The mcp CLI must be installed at ~/.local/bin/mcp. If not present:

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

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

Discovery Workflow

Step 1: Discover Available Tools

mcp tools <server-command>

Examples:

# 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

Step 2: Discover Resources (if supported)

mcp resources <server-command>

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

Step 3: Discover Prompts (if supported)

mcp prompts <server-command>

Prompts are pre-defined prompt templates the server provides.

Step 4: Get Detailed Info (JSON format)

# For full schema details including parameter types
mcp tools --format json <server-command>
mcp tools --format pretty <server-command>

Making Tool Calls

Basic Syntax

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

Examples

Read a file:

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

Write a file:

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

List directory:

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

Create entities (memory server):

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

Search (memory server):

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

Complex Parameters

For nested objects and arrays, ensure valid JSON:

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

# Table (default, human-readable)
mcp call <tool> --params '{}' <server>

# JSON (for parsing)
mcp call <tool> --params '{}' -f json <server>

# Pretty JSON (readable JSON)
mcp call <tool> --params '{}' -f pretty <server>

Reading Resources

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

Using Prompts

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

Server Aliases (for repeated use)

If using a server frequently during a session:

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

Authentication

HTTP Basic Auth

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

Bearer Token

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

Environment Variables (for Docker-based servers)

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)

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

HTTP (auto-detected for http/https URLs)

mcp tools https://example.com/mcp

SSE (Server-Sent Events)

mcp tools http://localhost:3001/sse
# Or explicitly:
mcp tools --transport sse http://localhost:3001

Common MCP Servers

Filesystem

# Allow access to specific directory
mcp tools npx -y @modelcontextprotocol/server-filesystem /path/to/allow

Memory (Knowledge Graph)

mcp tools npx -y @modelcontextprotocol/server-memory

GitHub

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

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

Puppeteer (Browser Automation)

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

Best Practices

1. Always Discover First

Before calling tools, run mcp tools to understand what's available and the exact parameter schema.

2. Use JSON Format for Parsing

When you need to process results programmatically:

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

3. Validate Parameters

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

4. Handle Errors Gracefully

Tool calls may fail. Check exit codes and stderr:

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

5. Use Aliases for Multi-Step Operations

If making several calls to the same server:

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

For safety, limit what tools are accessible:

# Only allow read operations
mcp guard --allow 'tools:read_*,list_*' --deny 'tools:write_*,delete_*' \
  npx -y @modelcontextprotocol/server-filesystem /home

Debugging

View Server Logs

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

Check Alias Configuration

cat ~/.mcpt/aliases.json

Verbose Output

Use --format pretty for detailed JSON output to debug parameter issues.

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

Example: Complete Workflow

# 1. Discover what's available
mcp tools npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 2. Check for resources
mcp resources npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 3. Create alias for convenience
mcp alias add proj npx -y @modelcontextprotocol/server-filesystem /home/user/project

# 4. Explore directory structure
mcp call directory_tree --params '{"path": "/home/user/project"}' proj

# 5. Read specific files
mcp call read_file --params '{"path": "/home/user/project/README.md"}' proj

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

# 7. Clean up alias
mcp alias remove proj

Troubleshooting

"command not found: mcp"

Ensure PATH is set: export PATH="$HOME/.local/bin:$PATH"

JSON parse errors

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

Server timeout

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

Permission denied

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

Weekly Installs

109

Repository

obra/superpowers-lab

GitHub Stars

243

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubFail SocketWarn SnykFail

Installed on

opencode93

codex90

gemini-cli85

github-copilot83

claude-code82

cursor76

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

118,000 周安装

MCP CLI 使用指南：动态调用 MCP 服务器工具，无需永久集成

🇨🇳中文介绍

MCP CLI：按需使用 MCP 服务器

何时使用此技能

先决条件

发现工作流程

步骤 1：发现可用工具

相关 Skills

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

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

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

进行工具调用

基本语法

示例

复杂参数

输出格式

读取资源

使用提示

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

身份验证

HTTP 基本身份验证

Bearer 令牌

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

传输类型

Stdio（npx/node 命令的默认值）

HTTP（对 http/https URL 自动检测）

SSE（服务器发送事件）

常见 MCP 服务器

文件系统

内存（知识图谱）

GitHub

Brave 搜索

Puppeteer（浏览器自动化）

最佳实践

1. 始终先进行发现

2. 使用 JSON 格式进行解析

3. 验证参数

4. 优雅地处理错误

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

6. 使用 Guard 限制功能

调试

查看服务器日志

检查别名配置

详细输出

快速参考

示例：完整工作流程

故障排除

"command not found: mcp"

JSON 解析错误

服务器超时

权限被拒绝

🇺🇸English

MCP CLI: On-Demand MCP Server Usage

When to Use This Skill

Prerequisites

Discovery Workflow

Step 1: Discover Available Tools

Step 2: Discover Resources (if supported)

Step 3: Discover Prompts (if supported)

Step 4: Get Detailed Info (JSON format)

Making Tool Calls

Basic Syntax

Examples

Complex Parameters

Output Formats

Reading Resources

Using Prompts

Server Aliases (for repeated use)

Authentication

HTTP Basic Auth

Bearer Token

Environment Variables (for Docker-based servers)

Transport Types

Stdio (default for npx/node commands)

HTTP (auto-detected for http/https URLs)

SSE (Server-Sent Events)

Common MCP Servers

Filesystem

Memory (Knowledge Graph)

GitHub