https://github.com/mcp2everything/mcp2tcp

Conenct TCP device to LLMs via MCP protocol
https://github.com/mcp2everything/mcp2tcp

Last synced: 2 months ago
JSON representation

Conenct TCP device to LLMs via MCP protocol

• Host: GitHub
• URL: https://github.com/mcp2everything/mcp2tcp
• Owner: mcp2everything
• License: mit
• Created: 2024-12-22T09:20:52.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2024-12-29T09:37:04.000Z (6 months ago)
• Last Synced: 2025-04-13T15:17:06.189Z (2 months ago)
• Language: Python
• Size: 5.64 MB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• mcp-index - mcp2tcp - Connects hardware devices with AI models using natural language commands, enabling real-time control and understanding of complex instructions. Integrates seamlessly with the Model Context Protocol (MCP) for resource management and tool invocation. (IoT and Device Control)

README

        
# mcp2tcp: 连接物理世界与AI大模型的桥梁 

[English](README_EN.md) | 简体中文



    

    
通过自然语言控制硬件，开启物联网新纪元



## 系统架构



    

    
mcp2tcp 系统架构图



## 工作流程



    

    
mcp2tcp 工作流程图



## 项目愿景

mcp2tcp 将TCP设备接入AI大模型的项目，它通过 Model Context Protocol (MCP) 将物理世界与 AI 大模型无缝连接。最终实现：

- 用自然语言控制你的硬件设备

- AI 实时响应并调整物理参数

- 让你的设备具备理解和执行复杂指令的能力

## 主要特性

- **智能TCP通信**

  - 自动检测和配置TCP设备 用户也可指定TCP号

  - 支持多种波特率（默认 115200）

  - 实时状态监控和错误处理

- **MCP 协议集成**

  - 完整支持 Model Context Protocol

  - 支持资源管理和工具调用

  - 灵活的提示词系统

## 支持的客户端

mcp2tcp 支持所有实现了 MCP 协议的客户端，包括：

| 客户端 | 特性支持 | 说明 |

|--------|----------|------|

| Claude Desktop | 完整支持 | 推荐使用，支持所有 MCP 功能 |

| Continue | 完整支持 | 优秀的开发工具集成 |

| Cline | 资源+工具 | 支持多种 AI 提供商 |

| Zed | 基础支持 | 支持提示词命令 |

| Sourcegraph Cody | 资源支持 | 通过 OpenCTX 集成 |

| Firebase Genkit | 部分支持 | 支持资源列表和工具 |

## 支持的 AI 模型

得益于灵活的客户端支持，mcp2tcp 可以与多种 AI 模型协同工作：

### 云端模型

- OpenAI (GPT-4, GPT-3.5)

- Anthropic Claude

- Google Gemini

- AWS Bedrock

- Azure OpenAI

- Google Cloud Vertex AI

### 本地模型

- LM Studio 支持的所有模型

- Ollama 支持的所有模型

- 任何兼容 OpenAI API 的模型

### 准备

Python3.11 或更高版本

Claude Desktop 或 Cline

## 快速开始

### 1. 安装

#### Windows用户

下载 [install.py](https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install.py) 

```bash

python install.py

```

#### macOS用户

```bash

# 下载安装脚本

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install_macos.py

# 运行安装脚本

python3 install_macos.py

```

#### Ubuntu/Raspberry Pi用户

```bash

# 下载安装脚本

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2tcp/main/install_ubuntu.py

# 运行安装脚本

python3 install_ubuntu.py

```

安装脚本会自动完成以下操作：

- ✅ 检查系统环境

- ✅ 安装必要的依赖

- ✅ 创建默认配置文件

- ✅ 配置Claude桌面版（如果已安装）

- ✅ 检查TCP设备

### 手动分步安装依赖

```bash

windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

MacOS

curl -LsSf https://astral.sh/uv/install.sh | sh

```

主要依赖uv工具，所以当python和uv以及Claude或Cline安装好后就可以了。

### 基本配置

在你的 MCP 客户端（如 Claude Desktop 或 Cline）配置文件中添加以下内容：

注意：如果使用的自动安装那么会自动配置Calude Desktop无需此步。

使用默认配置文件：

```json

{

    "mcpServers": {

        "mcp2tcp": {

            "command": "uvx",

            "args": [

                "mcp2tcp"

            ]

        }

    }

}

```

> 注意：修改配置后需要重启Cline或者Claude客户端软件

配置TCP和命令：

注意下面的配置默认为COM11 需要根据实际进行修改

```yaml

# config.yaml

tcp:

  # TCP服务器配置

  remote_ip: "127.0.0.1"  # 远端IP地址

  port: 9999  # 端口号

  connect_timeout: 3.0  # 连接超时时间，单位为秒

  receive_timeout: 2.0  # 接收超时时间，单位为秒

  communication_type: "client"  # 通信类型，client或server

  response_start_string: "CMD"  # 可选，TCP应答的开始字符串，默认为OK

commands:

  # PWM控制命令

  set_pwm:

    command: "CMD_PWM {frequency}"  # frequency为0-100的整数，表示PWM占空比

    need_parse: false  # 不需要解析响应内容

    data_type: "ascii"  # 数据类型，ascii或hex

    parameters:

      - name: "frequency"

        type: "integer"

        description: "PWM frequency value (0-100)"

        required: true

    prompts:

      - "把PWM调到最大 (frequency=100)"

      - "把PWM调到最小 (frequency=0)"

      - "请将PWM设置为{frequency} (0-100的整数)"

      - "关闭PWM (frequency=0)"

      - "把PWM调到一半 (frequency=50)"

```

## 配置说明

### 配置文件位置

配置文件（`config.yaml`）可以放在位置：

用户主目录（推荐个人使用）

```bash

# Windows系统

C:\Users\用户名\.mcp2tcp\config.yaml

# macOS系统

/Users/用户名/.mcp2tcp/config.yaml

# Linux系统

/home/用户名/.mcp2tcp/config.yaml

```

- 适用场景：个人配置

- 需要创建 `.mcp2tcp` 目录：

  ```bash

  # Windows系统（在命令提示符中）

  mkdir "%USERPROFILE%\.mcp2tcp"

  

  # macOS/Linux系统

  mkdir -p ~/.mcp2tcp

  ```

### TCP配置 命令配置进阶

在 `config.yaml` 中添加自定义命令：

使用真实TCP

```yaml

# config.yaml

 # PICO信息查询命令

  get_pico_info:

    command: "CMD_PICO_INFO"  # 实际发送的命令格式，server会自动添加\r\n

    need_parse: true  # 需要解析响应内容

    data_type: "ascii"  # 数据类型，ascii或hex

    prompts:

      - "查询Pico板信息"

      - "显示开发板状态"

```

指定配置文件：

比如指定加载Pico配置文件：Pico_config.yaml

```json

{

    "mcpServers": {

        "mcp2tcp": {

            "command": "uvx",

            "args": [

                "mcp2tcp",

                "--config",

                "Pico"  //指定配置文件名，不需要添加_config.yaml后缀

            ]

        }

    }

}

```

为了能使用多个TCP，我们可以新增多个mcp2tcp的服务 指定不同的配置文件名即可。

如果要接入多个设备，如有要连接第二个设备：

指定加载Pico2配置文件：Pico2_config.yaml

```json

{

    "mcpServers": {

        "mcp2tcp2": {

            "command": "uvx",

            "args": [

                "mcp2tcp",

                "--config",

                "Pico2"  //指定配置文件名，不需要添加_config.yaml后缀

            ]

        }

    }

}

```

## 测试

在开始使用之前，建议先进行测试以确保一切正常工作。

#### 1. 启动测试服务器

首先，启动测试目录下的 TCP 服务器来模拟硬件设备：

```bash

# 进入项目目录

cd tests

# 启动测试服务器

python tcp_server.py

```

服务器将在本地启动，监听端口 9999。你会看到类似这样的输出：

```

TCP server started on 127.0.0.1:9999

Waiting for connections...

```

### 启动客户端Claude 桌面版或Cline



    

    
Example in Cline



### 从源码快速开始

1. 从源码安装

```bash

# 通过源码安装：

git clone https://github.com/mcp2everything/mcp2tcp.git

cd mcp2tcp

# 创建虚拟环境

uv venv .venv

# 激活虚拟环境

# Windows:

.venv\Scripts\activate

# Linux/macOS:

source .venv/bin/activate

# 安装开发依赖

uv pip install --editable .

```

如果使用真实TCP

```yaml

# config.yaml

tcp:

  # TCP服务器配置

  remote_ip: "127.0.0.1"  # 远端IP地址

  port: 9999  # 端口号

  connect_timeout: 3.0  # 连接超时时间，单位为秒

  receive_timeout: 2.0  # 接收超时时间，单位为秒

  communication_type: "client"  # 通信类型，client或server

  response_start_string: "CMD"  # 可选，TCP应答的开始字符串，默认为OK

commands:

  # PWM控制命令

  set_pwm:

    command: "CMD_PWM {frequency}"  # frequency为0-100的整数，表示PWM占空比

    need_parse: false  # 不需要解析响应内容

    data_type: "ascii"  # 数据类型，ascii或hex

    parameters:

      - name: "frequency"

        type: "integer"

        description: "PWM frequency value (0-100)"

        required: true

    prompts:

      - "把PWM调到最大 (frequency=100)"

      - "把PWM调到最小 (frequency=0)"

      - "请将PWM设置为{frequency} (0-100的整数)"

      - "关闭PWM (frequency=0)"

      - "把PWM调到一半 (frequency=50)"

```

### MCP客户端配置

在使用支持MCP协议的客户端（如Claude Desktop或Cline）时，需要在客户端的配置文件中添加以下内容：

直接自动安装的配置方式

源码开发的配置方式

#### 使用默认演示参数：

```json

{

    "mcpServers": {

        "mcp2tcp": {

            "command": "uv",

            "args": [

                "--directory",

                "你的实际路径/mcp2tcp",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2tcp"

                "run",

                "mcp2tcp"

            ]

        }

    }

}

```

#### 指定参数文件名

```json

{

    "mcpServers": {

        "mcp2tcp": {

            "command": "uv",

            "args": [

                "--directory",

                "你的实际路径/mcp2tcp",  // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2tcp"

                "run",

                "mcp2tcp",

                "--config", // 可选参数，指定配置文件名

                "Pico"  // 可选参数，指定配置文件名，不需要添加_config.yaml后缀

            ]

        }

    }

}

```

### 配置文件位置

配置文件（`config.yaml`）可以放在不同位置，程序会按以下顺序查找：

#### 1. 当前工作目录（适合开发测试）

- 路径：`./config.yaml`

- 示例：如果你在 `C:\Projects` 运行程序，它会查找 `C:\Projects\config.yaml`

- 适用场景：开发和测试

- 不需要特殊权限

#### 2. 用户主目录（推荐个人使用）

```bash

# Windows系统

C:\Users\用户名\.mcp2tcp\config.yaml

# macOS系统

/Users/用户名/.mcp2tcp/config.yaml

# Linux系统

/home/用户名/.mcp2tcp/config.yaml

```

- 适用场景：个人配置

- 需要创建 `.mcp2tcp` 目录：

  ```bash

  # Windows系统（在命令提示符中）

  mkdir "%USERPROFILE%\.mcp2tcp"

  

  # macOS/Linux系统

  mkdir -p ~/.mcp2tcp

  ```

#### 3. 系统级配置（适合多用户环境）

```bash

# Windows系统（需要管理员权限）

C:\ProgramData\mcp2tcp\config.yaml

# macOS/Linux系统（需要root权限）

/etc/mcp2tcp/config.yaml

```

- 适用场景：多用户共享配置

- 创建目录并设置权限：

  ```bash

  # Windows系统（以管理员身份运行）

  mkdir "C:\ProgramData\mcp2tcp"

  

  # macOS/Linux系统（以root身份运行）

  sudo mkdir -p /etc/mcp2tcp

  sudo chown root:root /etc/mcp2tcp

  sudo chmod 755 /etc/mcp2tcp

  ```

程序会按照上述顺序查找配置文件，使用找到的第一个有效配置文件。根据你的需求选择合适的位置：

- 开发测试：使用当前目录

- 个人使用：建议使用用户主目录（推荐）

- 多用户环境：使用系统级配置（ProgramData或/etc）

3. 运行服务器：

```bash

# 确保已激活虚拟环境

.venv\Scripts\activate

# 运行服务器（使用默认配置config.yaml 案例中用的LOOP_BACK 模拟TCP，无需真实TCP和TCP设备）

uv run src/mcp2tcp/server.py

或

uv run mcp2tcp

# 运行服务器（使用指定配置Pico_config.yaml）

uv run src/mcp2tcp/server.py --config Pico

或

uv run mcp2tcp --config Pico

```

## 文档

- [安装指南](./docs/zh/installation.md)

- [API文档](./docs/zh/api.md)

- [配置说明](./docs/zh/configuration.md)