AI导哈

MCP服务器管理工具

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

  • by estiens
  • Shell
  • 本地部署
  • 更新于
在 GitHub 查看 estiens/mcptool.sh

使用说明

MCP工具文档

概述

MCP工具是一个用于管理模型上下文协议（MCP）服务器的命令行实用程序。它为使用Claude和Cursor等工具运行、配置和集成各种MCP服务器提供了一个统一的界面。

主要特点

核心功能

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

高级功能

  • 克劳德集成：轻松将服务器定义添加到Claude MCP
  • 光标集成：将服务器定义添加到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配置文件的替代路径

壳牌与Autoloader的集成

自动加载器功能创建了一个脚本，可以在您的 .zshrc 文件，为MCP服务器命令提供方便的shell函数和选项卡完成。

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

    ./mcptool.sh autoloader

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

    source ~/.mcp_autoloader.zsh

  3. 重新加载shell后，您可以使用这些带有制表符的命令：

    • 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工具使向Claude和Cursor MCP添加服务器定义变得容易：

克劳德集成

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

光标集成

# 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）
    • 安装对话框（用于交互模式）： 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错误无效

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

平台特定问题

  • macOS：The sed -i 命令在macOS上的工作方式不同。脚本会自动处理此问题。
  • Linux：没有已知的平台特定问题。
  • 视窗：不直接支持。考虑使用WSL（Linux的Windows子系统）。

贡献

要将新的MCP服务器添加到库中，请执行以下操作：

  1. 编辑JSON配置文件以添加新的服务器定义
  2. 使用MCP工具测试服务器
  3. 记录服务器的用途、要求和使用情况
  4. 如果您正在为主存储库做出贡献，请提交拉取请求

许可证

此工具未经DWTFYouWant许可而提供

相关 MCP