MCP Tool Documentation

MCP 工具文档

概述

MCP Tool 是一款用于管理模型上下文协议（MCP）服务的命令行工具。它提供统一的界面，用于运行、配置各种 MCP 服务，并将它们与 Claude 和 Cursor 等工具集成。

主要功能

核心功能

• 列出可用的 MCP 服务和服务组
• 单独运行 MCP 服务或以服务组的形式运行
• 显示服务的详细信息
• 为所有服务生成完整文档
• 以 JSON 格式输出服务定义

高级功能

• Claude 集成：轻松将服务定义添加到 Claude MCP
• Cursor 集成：将服务定义添加到 Cursor MCP 配置
• .zshrc 自动加载器：集成到 Shell 环境并提供自动补全
• 交互模式：通过友好的菜单选择和管理服务
• 配置向导：设置服务所需的环境变量
• 改进的错误处理：问题发生时提供更好的反馈
• 增强的帮助系统：提供各命令的详细用法信息

安装

1. 将脚本文件克隆或下载到首选位置：

   git clone https://github.com/your-username/mcptool.git
   cd mcptool
   

2. 将主脚本设为可执行：

   chmod +x mcptool.sh
   

3. 确保已安装所需的依赖项：

   • jq：JSON 处理器（解析服务配置所需）
   • dialog：可选，用于交互模式

4. （可选）创建别名以便于访问：

   alias mcpt='/path/to/mcptool.sh'
   

用法

主脚本（mcptool.sh）是所有功能的统一命令中心。

基本命令

MCP Tool v1.2.0 - Manage MCP Servers

Usage: ./bin/mcptool.sh <command> [target] [options]

Commands:
  list                   List servers and groups
  run <target> [--bg]    Run a server or group. Groups run in separate terminals.
                         Use --background or --bg to run in detached background mode.
  add <server> <opts>    Add server definition to a required backend/file.
                         Target Options (required): --claude | --cursor [--global] | --json <file> | <file>
  info <target> [-v]     Show info for a server or group (use -v for group details)
  json <target>          Output server/group JSON definition
  docs                   Show documentation for all servers
  interactive            Launch interactive TUI menu (requires 'dialog')
  autoloader             Generate shell autocompletion script
  help <cmd>             Show detailed help for a command

Common Options:
  --servers-file=<path>  Specify servers file (default: /Users/estiens/code/mcptool/config/servers.json)
  --groups-file=<path>   Specify groups file (default: /Users/estiens/code/mcptool/config/groups.json)
  -v, --verbose          Show detailed output (used with 'info group')
  --background, --bg     Run server/group in background (used with 'run')

Note: The tool supports both JSON and YAML formats for configuration files

Run './bin/mcptool.sh help <command>' for more details on a specific command.

常用选项

• -v, --verbose：显示详细输出（与 info 命令搭配使用时尤其有用）
• --project：使用项目级作用域进行 Claude/Cursor 集成（默认）
• --global：使用全局/用户级作用域进行 Claude/Cursor 集成
• --json-file=<path>：指定自定义 JSON 文件位置

环境变量

• MCP_CONFIG_FILE：JSON 配置文件的备用路径

通过自动加载器集成 Shell

自动加载器功能会创建一个脚本，可在 .zshrc 文件中引入，以便为 MCP 服务命令提供便捷的 Shell 函数和 Tab 补全。

1. 生成自动加载器文件：

   ./mcptool.sh autoloader
   

2. 将以下行添加到 .zshrc 文件中：

   source ~/.mcp_autoloader.zsh
   

3. 重新加载 Shell 后，即可使用以下命令并通过 Tab 补全：

   • mcpt list：列出所有可用服务和服务组
   • mcpt run <server|group>：运行指定服务或服务组
   • mcpt info <server|group>：获取服务或服务组的信息
   • mcpt json <server|group>：获取服务或服务组的 JSON 定义
   • mcpt add <server> --claude|--cursor [--global]|--json <file>|<file>：添加服务定义
   • mcpt docs：生成完整文档
   • mcpt interactive：启动交互模式

交互模式

交互模式提供了一个友好的菜单界面，用于管理 MCP 服务。使用以下命令启动：

./mcptool.sh interactive

菜单允许你：

• 运行服务
• 获取服务信息
• 运行服务组
• 获取服务组信息
• 查看文档
• 使用 add 命令添加服务定义（在交互模式之外）
• 退出应用程序

Claude 和 Cursor 集成

MCP Tool 让你可以轻松地将服务定义添加到 Claude 和 Cursor MCP：

Claude 集成

# Add a server definition to Claude MCP (project scope)
./mcptool.sh add server_name --claude

# Add a server definition to Claude MCP (global/user scope)
./mcptool.sh add server_name --claude --global

# Add a server definition, overwriting existing Claude config
./mcptool.sh add server_name --claude --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

Cursor 集成

# Add a server definition to Cursor MCP (project scope - ./.cursor/mcp.json)
./mcptool.sh add server_name --cursor

# Add a server definition to Cursor MCP (global scope - ~/.cursor/mcp.json)
./mcptool.sh add server_name --cursor --global

# Add a server definition, overwriting existing Cursor config
./mcptool.sh add server_name --cursor --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

添加到 JSON/YAML 文件

# Add a server definition to a specific JSON file
./mcptool.sh add server_name --json path/to/your/config.json

# Add a server definition, overwriting the target JSON file
./mcptool.sh add server_name --json path/to/your/config.json --overwrite

# Add a server definition to a specific YAML file (or any text file)
./mcptool.sh add server_name path/to/your/config.yaml

# Add a server definition, overwriting the target YAML file
./mcptool.sh add server_name path/to/your/config.yaml --overwrite

配置文件

MCP 服务定义在 JSON 配置文件中，结构如下：

{
  "servers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "required_env": ["ENV_VAR1", "ENV_VAR2"],
      "description": "Server description"
    }
  },
  "groups": {
    "group_name": ["server1", "server2"]
  }
}

故障排除

常见问题

1. 找不到 JSON 文件

   • 确保使用 --json-file=path/to/file 指定了正确的路径
   • 检查 MCP_CONFIG_FILE 环境变量是否设置正确
   • 默认位置是脚本所在目录：mcp_servers.json

2. 缺少依赖项

   • 安装 jq：brew install jq（macOS）或 sudo apt-get install -y jq（Ubuntu/Debian）
   • 安装 dialog（用于交互模式）：brew install dialog（macOS）或 sudo apt-get install -y dialog（Ubuntu/Debian）

3. 缺少环境变量

   • 某些服务需要环境变量。查看服务文档（通过 mcptool docs 或 mcptool info <server>）了解所需变量。
   • 在环境中或 .env 文件（例如 .env.mcp）中设置，并加载该文件（source .env.mcp）。

4. add 命令失败

   • 确保提供了有效的目标：--claude、--cursor [--global]、--json <file> 或文件名 <file>。
   • 对于 --claude：确保已安装 Claude CLI，且它位于 PATH 中。
   • 对于 --cursor 或文件目标：检查目标目录/文件是否可写。

5. JSON 无效错误

   • 使用 jq empty your_file.json 验证 JSON 文件
   • 常见问题包括缺少逗号、多余逗号或字符串引号格式不正确

特定平台问题

• macOS：sed -i 命令在 macOS 上的工作方式有所不同。脚本会自动处理。
• Linux：暂无已知的平台特定问题。
• Windows：不直接支持。建议使用 WSL（适用于 Linux 的 Windows 子系统）。

贡献

向库中添加新的 MCP 服务：

1. 编辑 JSON 配置文件，添加新的服务定义
2. 使用 MCP Tool 测试服务
3. 记录服务的用途、要求和用法
4. 如果要为主仓库做贡献，请提交拉取请求

许可证

此工具依据 DWTFYouWant 的 Unlicense 提供