Swiss Army Knife for MCP Servers

<p align="center">
  <img src="./.github/resources/logo.png" alt="MCP Tools" height="150">
</p>

<p align="center">
  <h1 align="center">MCP 服务器的瑞士军刀</h1>
  <p align="center">
    一个用于与 MCP (模型上下文协议) 服务器交互的综合命令行界面。
    <br>
    从任何 MCP 兼容的服务器发现、调用和管理工具、资源和提示。
    <br>
    支持多种传输方法、输出格式，并包含强大的模拟和代理服务器功能。
  </p>
</p>

[![博客文章](https://img.shields.io/badge/Blog-阅读关于%20MCP%20Tools-blue)](https://blog.fka.dev/blog/2025-03-27-mcp-inspector-vs-mcp-tools/)

## 目录

- [概述](#overview)
- [MCP Inspector 和 MCP Tools 之间的区别](https://blog.fka.dev/blog/2025-03-27-mcp-inspector-vs-mcp-tools/)
- [安装](#installation)
  - [使用 Homebrew](#using-homebrew)
  - [从源代码](#from-source)
- [快速上手](#getting-started)
- [特性](#features)
  - [传输选项](#transport-options)
  - [输出格式](#output-formats)
  - [命令](#commands)
  - [交互式 Shell](#interactive-shell)
  - [项目脚手架](#project-scaffolding)
- [服务器别名](#server-aliases)
- [LLM 应用配置管理](#llm-apps-config-management)
- [服务器模式](#server-modes)
  - [模拟服务器模式](#mock-server-mode)
  - [代理模式](#proxy-mode)
- [示例](#examples)
  - [基本用法](#basic-usage)
  - [脚本集成](#script-integration)
  - [调试](#debugging)
- [贡献](#contributing)
- [路线图](#roadmap)
- [许可证](#license)

## 概述

MCP Tools 提供了一个通用的 CLI，用于处理模型上下文协议 (MCP) 服务器。它使您能够：

- 发现和调用 MCP 服务器提供的工具
- 访问和利用 MCP 服务器公开的资源
- 创建模拟服务器以测试客户端应用程序
- 将 MCP 请求代理到 shell 脚本以实现轻松扩展
- 创建交互式 shell 以探索和使用 MCP 服务器
- 使用 TypeScript 支持搭建新的 MCP 项目
- 以各种样式格式化输出（JSON、美化打印、表格）
- 支持所有传输方法（HTTP、stdio）

<p align="center">
  <img src=".github/resources/screenshot.png" alt="MCP Tools 截图" width="700">
</p>

## 安装

### 使用 Homebrew

```bash
brew tap f/mcptools
brew install mcp

❕ 该二进制文件安装为 mcp，但也可以作为 mcpt 访问，以避免与其他可能使用 mcp 命令名称的工具冲突。

从源代码

go install github.com/f/mcptools/cmd/mcptools@latest

该二进制文件将安装为 mcptools，但为了方便起见，可以将其别名为 mcpt。

快速上手

开始使用 MCP Tools 的最简单方法是连接到 MCP 服务器并列出可用的工具：

# 列出文件系统服务器上的所有可用工具
mcp tools npx -y @modelcontextprotocol/server-filesystem ~

# 调用特定工具
mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~

# 打开交互式 shell
mcp shell npx -y @modelcontextprotocol/server-filesystem ~

特性

MCP Tools 支持广泛的特性，用于与 MCP 服务器交互：

用法:
  mcp [命令]

可用命令:
  version       打印版本信息
  tools         列出 MCP 服务器上的可用工具
  resources     列出 MCP 服务器上的可用资源
  prompts       列出 MCP 服务器上的可用提示
  call          调用 MCP 服务器上的工具、资源或提示
  get-prompt    获取 MCP 服务器上的提示
  read-resource 读取 MCP 服务器上的资源
  shell         启动 MCP 命令的交互式 shell
  mock          创建具有工具、提示和资源的模拟 MCP 服务器
  proxy         将 MCP 工具请求代理到 shell 脚本
  alias         管理 MCP 服务器别名
  configs       管理 MCP 服务器配置
  new           创建一个新的 MCP 项目组件
  help          关于任何命令的帮助
  completion    为指定的 shell 生成自动补全脚本

标志:
  -f, --format string   输出格式 (table, json, pretty) (默认 "table")
  -h, --help            mcp 的帮助
  -p, --params string   传递给工具的参数的 JSON 字符串 (用于 call 命令) (默认 "{}")

使用 "mcp [command] --help" 获取有关命令的更多信息。

传输选项

MCP Tools 支持多种传输方法，用于与 MCP 服务器通信：

Stdio 传输

使用 stdin/stdout 通过 JSON-RPC 2.0 与 MCP 服务器通信。这对于实现 MCP 协议的命令行工具很有用。

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

HTTP SSE 传输

使用 HTTP 和服务器发送事件 (SSE) 通过 JSON-RPC 2.0 与 MCP 服务器通信。这对于连接到实现 MCP 协议的远程服务器很有用。

mcp tools http://127.0.0.1:3001

# 示例：使用 everything 示例服务器
# docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1

注意： HTTP SSE 当前仅支持 MCP 协议版本 2024-11-05。

输出格式

MCP Tools 支持三种输出格式，以适应不同的需求：

表格格式（默认）

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

默认格式现在以彩色 man-page 样式显示工具：

read_file(path:str, [limit:int], [offset:int])
     从文件系统读取文件

list_dir(path:str)
     列出目录内容

grep_search(pattern:str, [excludePatterns:str[]])
     使用模式搜索文件

edit_file(edits:{newText:str,oldText:str}[], path:str)
     使用多个文本替换编辑文件

该格式的关键特性：

• 函数名称以粗体青色显示
• 必需参数以绿色显示（例如，path:str）
• 可选参数显示在黄色方括号中（例如，[limit:int]）
• 数组类型用 [] 后缀表示（例如，str[]）
• 对象类型在花括号中显示其属性（例如，{prop1:type1,prop2:type2}）
• 嵌套对象以递归方式显示（例如，{notifications:{enabled:bool,sound:bool}}）
• 类型名称缩短以提高可读性（例如，str 而不是 string，int 而不是 integer）
• 描述缩进并以灰色显示
• 参数顺序一致，必需参数首先列出

JSON 格式（紧凑）

mcp tools --format json npx -y @modelcontextprotocol/server-filesystem ~

Pretty JSON 格式（缩进）

mcp tools --format pretty npx -y @modelcontextprotocol/server-filesystem ~

命令

MCP Tools 包括几个用于与 MCP 服务器交互的核心命令：

列出可用工具

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

列出可用资源

mcp resources npx -y @modelcontextprotocol/server-filesystem ~

列出可用提示

mcp prompts npx -y @modelcontextprotocol/server-filesystem ~

调用工具

mcp call read_file --params '{"path":"/path/to/file"}' npx -y @modelcontextprotocol/server-filesystem ~

调用资源

mcp call resource:test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

或者

mcp read-resource test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

调用提示

mcp get-prompt simple_prompt npx -y @modelcontextprotocol/server-everything -f json | jq ".messages[0].content.text"

交互式 Shell

交互式 shell 模式允许您在单个会话中运行多个 MCP 命令：

mcp shell npx -y @modelcontextprotocol/server-filesystem ~

这将打开一个具有以下功能的交互式 shell：

mcp tools shell
已连接到: npx -y @modelcontextprotocol/server-filesystem /Users/fka

mcp > 键入 '/h' 获取帮助或 '/q' 退出
mcp > tools
read_file(path:str, [limit:int], [offset:int])
     从文件系统读取文件

list_dir(path:str)
     列出目录内容

grep_search(pattern:str, [excludePatterns:str[]])
     使用模式搜索文件

edit_file(edits:{newText:str,oldText:str}[], path:str)
     使用多个文本替换编辑文件

# 支持直接工具调用
mcp > read_file {"path":"README.md"}
...README.md 的内容...

# 使用复杂对象参数调用工具
mcp > edit_file {"path":"main.go","edits":[{"oldText":"foo","newText":"bar"}]}
...编辑操作的结果...

# 获取帮助
mcp > /h
MCP Shell 命令:
  tools                      列出可用工具
  resources                  列出可用资源
  prompts                    列出可用提示
  call <entity> [--params '{...}']  调用工具、资源或提示
  format [json|pretty|table] 获取或设置输出格式
特殊命令:
  /h, /help                  显示此帮助
  /q, /quit, exit            退出 shell

项目脚手架

MCP Tools 提供了一个脚手架特性，可以快速创建具有 TypeScript 的新 MCP 服务器：

mkdir my-mcp-server
cd my-mcp-server

# 创建具有特定组件的项目
mcp new tool:calculate resource:file prompt:greet

# 创建具有特定 SDK 的项目（目前仅支持 TypeScript/ts）
mcp new tool:calculate --sdk=ts

# 创建具有特定传输类型的项目
mcp new tool:calculate --transport=stdio
mcp new tool:calculate --transport=sse

脚手架创建一个完整的项目结构，包括：

• 使用所选传输（stdio 或 SSE）的服务器设置
• 具有现代 ES 模块的 TypeScript 配置
• 具有适当 MCP 接口的组件实现
• 自动连接导入和初始化

脚手架完成后，您可以构建并运行您的 MCP 服务器：

# 安装依赖项
npm install

# 构建 TypeScript 代码
npm run build

# 使用 MCP Tools 测试服务器
mcp tools node build/index.js

项目模板存储在以下位置之一：

• 本地 ./templates/ 目录
• 用户的主目录：~/.mcpt/templates/
• Homebrew 安装路径 (/opt/homebrew/Cellar/mcp/v#.#.#/templates)

通过 Homebrew 安装时，模板会自动安装到您的主目录。但是如果您使用源代码安装，则需要运行 make install-templates。

服务器别名

MCP Tools 允许您使用友好的别名保存和重用服务器命令：

# 添加新的服务器别名
mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/

# 列出所有已注册的服务器别名
mcp alias list

# 删除服务器别名
mcp alias remove myfs

# 将别名与任何 MCP 命令一起使用
mcp tools myfs
mcp call read_file --params '{"path":"README.md"}' myfs

服务器别名存储在 $HOME/.mcpt/aliases.json 中，并提供了一种方便的方式来处理常用的 MCP 服务器，而无需重复键入长命令。

LLM 应用配置管理

MCP Tools 提供了一个强大的配置管理系统，可以帮助您跨多个应用程序处理 MCP 服务器配置：

🚧 此功能目前仅适用于 macOS。

# 扫描所有受支持的应用程序中的 MCP 服务器配置
mcp configs scan

# 列出所有配置（configs view --all 的别名）
mcp configs ls

# 按别名查看特定配置
mcp configs view vscode

# 在配置中添加或更新服务器
mcp configs set vscode my-server npm run mcp-server
mcp configs set cursor my-api https://api.example.com/mcp --headers "Authorization=Bearer token"

# 一次添加到多个配置
mcp configs set vscode,cursor,claude-desktop my-server npm run mcp-server

# 从配置中删除服务器
mcp configs remove vscode my-server

# 为自定义配置文件创建别名
mcp configs alias myapp ~/myapp/config.json

# 同步和合并来自多个来源的配置
mcp configs sync vscode cursor --output vscode --default interactive

# 将命令行转换为 MCP 服务器 JSON 配置格式
mcp configs as-json mcp proxy start
# 输出: {"command":"mcp","args":["proxy","start"]}

# 将 URL 转换为 MCP 服务器 JSON 配置格式
mcp configs as-json https://api.example.com/mcp --headers "Authorization=Bearer token"
# 输出: {"url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer token"}}

配置通过 $HOME/.mcpt/configs.json 中的中央注册表进行管理，其中包含以下预定义别名：

• VS Code 和 VS Code Insiders
• Windsurf
• Cursor
• Claude Desktop 和 Claude Code

该系统自动以彩色格式显示按来源分组的服务器配置，显示命令行或 URL 信息、标头和环境变量。

mcp configs scan 命令在以下位置查找 MCP 服务器配置：

• Visual Studio Code
• Visual Studio Code Insiders
• Windsurf
• Cursor
• Claude Desktop

示例输出：

VS Code Insiders
  GitHub (stdio):
    docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Claude Desktop
  Proxy (stdio):
    mcp proxy start

  My Files (stdio):
    npx -y @modelcontextprotocol/server-filesystem ~/

奖励

一次性将官方 GitHub MCP Server 添加到 Windsurf、Cursor 和 VS Code：

mcp configs set windsurf,cursor,vscode GitHub \
  --env "GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxx" \
  docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

<p align="center"> <img src=".github/resources/configs.png" alt="MCP 配置截图" width="700"> </p>

服务器模式

MCP Tools 可以作为客户端和服务器运行，并提供两种服务器模式：

模拟服务器模式

模拟服务器模式创建一个模拟的 MCP 服务器，用于测试客户端，而无需实现完整的服务器：

# 创建一个具有简单工具的模拟服务器
mcp mock tool hello_world "一个简单的问候工具"

# 创建一个具有多种实体类型的模拟服务器
mcp mock tool hello_world "一个问候工具" \
       prompt welcome "一个欢迎提示" "你好 {{name}}，欢迎来到 {{location}}！" \
       resource docs://readme "文档" "模拟 MCP 服务器\n这是一个模拟服务器"

模拟服务器的特性：

• 完整的初始化握手
• 具有标准化模式的工具列表
• 具有简单响应的工具调用
• 资源列表和读取
• 具有参数替换的提示列表和检索
• 详细的请求/响应日志记录到 ~/.mcpt/logs/mock.log

使用提示模板

对于提示，{{双花括号}} 中的任何文本都会自动检测为参数：

# 创建一个具有姓名和位置参数的提示
mcp mock prompt greeting "问候模板" "你好 {{name}}！欢迎来到 {{location}}。"

当客户端请求提示时，它可以为这些参数提供值，这些值将在响应中被替换。

代理模式

代理模式允许您将 shell 脚本或内联命令注册为 MCP 工具，从而可以轻松扩展 MCP 功能，而无需编写代码：

# 将 shell 脚本注册为 MCP 工具
mcp proxy tool add_operation "添加 a 和 b" "a:int,b:int" ./examples/add.sh

# 将内联命令注册为 MCP 工具
mcp proxy tool add_operation "添加 a 和 b" "a:int,b:int" -e 'echo "总计是 $a + $b = $(($a+$b))"'

# 注销工具
mcp proxy tool --unregister add_operation

# 启动代理服务器
mcp proxy start

使用代理服务器运行 mcp tools localhost:3000 将显示已注册的工具及其参数：

add_operation(a:int, b:int)
     添加 a 和 b

count_files(dir:str, [include:str[]])
     计算目录中的文件，带有可选过滤器

这种新格式清楚地显示了每个工具接受哪些参数，从而更容易理解如何使用它们。数组用 [] 后缀表示（例如，str[]），并且类型名称缩短以提高可读性。

工作原理

1. 使用工具名称、描述和参数规范注册 shell 脚本或内联命令
2. 启动实现 MCP 协议的代理服务器
3. 调用工具时，参数作为环境变量传递给脚本/命令
4. 脚本/命令的输出作为工具响应返回

示例脚本和命令

添加数字 (add.sh):

#!/bin/bash
# 从环境变量获取值
if [ -z "$a" ] || [ -z "$b" ]; then
  echo "错误：缺少必需参数 'a' 或 'b'"
  exit 1
fi

# 执行加法
result=$(($a + $b))
echo "$a 和 $b 的总和是 $result"

内联命令示例：

# 简单加法
mcp proxy tool add_op "添加给定的数字" "a:int,b:int" -e 'echo "总计是 $a + $b = $(($a+$b))"'

# 自定义问候语
mcp proxy tool greet "问候用户" "name:string,greeting:string,formal:bool" -e '
if [ "$formal" = "true" ]; then
  title="先生/女士"
  echo "${greeting:-你好}，${title} ${name}。今天有什么可以帮到您？"
else
  echo "${greeting:-你好}，${name}！很高兴见到你！"
fi
'

# 文件操作
mcp proxy tool count_lines "计算文件中的行数" "file:string" -e "wc -l < \"$file\""

配置和日志记录

• 工具在 ~/.mcpt/proxy_config.json 中注册
• 代理服务器将所有请求和响应记录到 ~/.mcpt/logs/proxy.log
• 使用 --unregister 从配置中删除工具

示例

基本用法

列出文件系统服务器中的工具：

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

使用漂亮的 JSON 输出调用工具：

mcp call read_file --params '{"path":"README.md"}' --format pretty npx -y @modelcontextprotocol/server-filesystem ~

脚本集成

将代理模式与简单的 shell 脚本一起使用：

# 1. 创建一个简单的 shell 脚本用于加法
cat > add.sh << 'EOF'
#!/bin/bash
# 从环境变量获取值
if [ -z "$a" ] || [ -z "$b" ]; then
  echo "错误：缺少必需参数 'a' 或 'b'"
  exit 1
fi
result=$(($a + $b))
echo "$a 和 $b 的总和是 $result"
EOF

# 2. 使其可执行
chmod +x add.sh

# 3. 将其注册为 MCP 工具
mcp proxy tool add_numbers "添加两个数字" "a:int,b:int" ./add.sh

# 4. 在一个终端中，启动代理服务器
mcp proxy start

# 5. 在另一个终端中，您可以将其作为 MCP 工具调用
mcp call add_numbers --params '{"a":5,"b":3}' --format pretty

调试

Tailing 日志以调试您的代理或模拟服务器：

# 对于模拟服务器日志
tail -f ~/.mcpt/logs/mock.log

# 对于代理服务器日志
tail -f ~/.mcpt/logs/proxy.log

# 实时查看所有日志（在 macOS/Linux 上）
find ~/.mcpt/logs -name "*.log" -exec tail -f {} \;

贡献

欢迎贡献！请参阅我们的 贡献指南，了解如何提交拉取请求、报告问题以及为项目做出贡献的详细信息。

路线图

以下特性计划在未来的版本中发布：

• 身份验证：支持安全的身份验证机制

许可证

该项目已获得 MIT 许可证的许可。

感谢

感谢 Fatih Taskiran 的徽标设计。