使用说明

项目简介

mcp2tcp 是一个连接物理世界和 AI 大模型的桥梁，它实现了 Model Context Protocol (MCP) 服务器，可以将 TCP 设备接入到支持 MCP 协议的 AI 客户端，例如 Claude、Continue、Cline 等。通过 mcp2tcp，用户可以使用自然语言控制和查询 TCP 设备的硬件状态，实现智能物联网应用。

主要功能点

TCP 设备接入: 支持通过 TCP 协议与硬件设备通信，实现对物理世界的控制和数据采集。
MCP 协议支持: 完整实现了 MCP 服务器协议，可以与任何兼容 MCP 协议的客户端进行交互。
资源与工具管理: 支持定义和管理 TCP 命令作为工具，供 LLM 客户端调用，实现特定硬件功能。
灵活的配置: 通过 YAML 配置文件管理 TCP 连接参数和命令，支持自定义命令和提示词。
多客户端支持: 兼容多种实现了 MCP 协议的客户端，如 Claude Desktop, Continue, Cline, Zed, Sourcegraph Cody, Firebase Genkit。

安装步骤

前提条件

Python 3.11 或更高版本

安装方法

下载安装脚本：根据你的操作系统，下载对应的安装脚本：
- Windows 用户: 下载 install.py
- macOS 用户: 下载 install_macos.py
- Ubuntu/Raspberry Pi 用户: 下载 install_ubuntu.py

运行安装脚本：在终端或命令提示符中，导航到脚本所在目录并执行以下命令：

python install.py  # Windows
python3 install_macos.py # macOS
python3 install_ubuntu.py # Ubuntu/Raspberry Pi

安装脚本会自动完成环境检查、依赖安装、配置文件创建和客户端配置等步骤。

手动安装 (可选)：如果你希望手动安装，可以参考 README 文档中的源码安装步骤，使用 'uv' 包管理器安装依赖和项目。

服务器配置

MCP 服务器的配置主要在客户端完成，你需要配置 MCP 客户端以连接到 mcp2tcp 服务器。以下是在 MCP 客户端 (如 Claude Desktop 或 Cline) 中配置 mcp2tcp 服务器的示例配置 (JSON 格式)：

基础配置 (默认配置)

{
  "mcpServers": {
    "mcp2tcp": {
      "command": "uvx",
      "args": [
        "mcp2tcp"
      ]
    }
  }
}

参数说明:

'"mcpServers"': MCP 服务器配置的根节点。
'"mcp2tcp"': 自定义的服务器名称，用于在客户端中标识 mcp2tcp 服务器，可以修改为其他名称。
'"command"': 'uvx'。 'uvx' 是 'uv' 包管理器提供的可以直接运行 Python 包的命令，确保 mcp2tcp 服务器能够被正确执行。
'"args"': '["mcp2tcp"]'。指定 'uvx' 命令的参数，'"mcp2tcp"' 表示运行 'mcp2tcp' 包，这将启动 'mcp2tcp' 服务器。

指定配置文件 (可选)

如果你需要使用特定的配置文件，例如 'Pico_config.yaml'，可以使用 '--config' 参数指定配置文件名 (不需要添加 '_config.yaml' 后缀)：

{
  "mcpServers": {
    "mcp2tcp": {
      "command": "uvx",
      "args": [
        "mcp2tcp",
        "--config",
        "Pico"
      ]
    }
  }
}

参数说明:

'"args"': '["mcp2tcp", "--config", "Pico"]'。在原有的参数基础上，添加了 '--config Pico'，指示 'mcp2tcp' 服务器加载名为 'Pico_config.yaml' 的配置文件。

配置文件位置

'mcp2tcp' 服务器的配置文件 ('config.yaml') 默认会按照以下顺序查找：

当前工作目录 ('./config.yaml')
用户主目录 ('~/.mcp2tcp/config.yaml')
系统级配置目录 ('/etc/mcp2tcp/config.yaml' 或 'C:\ProgramData\mcp2tcp\config.yaml')

建议个人用户将配置文件放置在用户主目录下的 '.mcp2tcp' 文件夹中。

基本使用方法

启动 mcp2tcp 服务器: 安装完成后，在终端或命令提示符中运行 'uv run mcp2tcp' 命令 (或使用 'uv run mcp2tcp --config <配置文件名>' 指定配置文件)。
配置 MCP 客户端: 将上述提供的 JSON 配置添加到你的 MCP 客户端 (如 Claude Desktop 或 Cline) 的配置文件中。
重启 MCP 客户端: 重启客户端软件使配置生效。
使用自然语言控制硬件: 在 MCP 客户端中，可以使用自然语言指令 (例如配置文件中 'prompts' 字段定义的提示词) 来调用 mcp2tcp 服务器提供的工具，从而控制连接的 TCP 设备。

例如, 如果你配置了 'set_pwm' 命令和相关的提示词 "把PWM调到最大 (frequency=100)"，你可以在 Claude 中输入 "把PWM调到最大"，客户端会将指令发送给 mcp2tcp 服务器，服务器会通过 TCP 协议向硬件设备发送相应的 PWM 控制命令。

关键词