mcp2tcp: Bridging the Physical World with Large AI Models

English | Simplified Chinese

System Architecture

Workflow

Project Vision

mcp2tcp is a project that connects TCP devices to large AI models. It seamlessly integrates the physical world with large AI models through the Model Context Protocol (MCP). The ultimate goal is to:

• Control your hardware devices using natural language
• Enable real-time AI response and adjustment of physical parameters
• Make your devices capable of understanding and executing complex instructions

Key Features

• Intelligent TCP Communication

  • Automatic detection and configuration of TCP devices; users can also specify the TCP number
  • Supports multiple baud rates (default 115200)
  • Real-time status monitoring and error handling

• MCP Protocol Integration

  • Full support for the Model Context Protocol
  • Supports resource management and tool invocation
  • Flexible prompt system

Supported Clients

mcp2tcp supports all clients that implement the MCP protocol, including:

Supported AI Models

Thanks to flexible client support, mcp2tcp can work with a variety of AI models:

Cloud Models

• OpenAI (GPT-4, GPT-3.5)
• Anthropic Claude
• Google Gemini
• AWS Bedrock
• Azure OpenAI
• Google Cloud Vertex AI

Local Models

• All models supported by LM Studio
• All models supported by Ollama
• Any model compatible with the OpenAI API

Prerequisites

• Python 3.11 or higher
• Claude Desktop or Cline

Quick Start

1. Installation

Windows Users

Download install.py bash python install.py

macOS Users

bash

Download the installation script

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

Run the installation script

python3 install_macos.py

Ubuntu/Raspberry Pi Users

bash

Download the installation script

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

Run the installation script

python3 install_ubuntu.py

The installation script will automatically:

• ✅ Check the system environment
• ✅ Install necessary dependencies
• ✅ Create default configuration files
• ✅ Configure Claude Desktop (if installed)
• ✅ Check TCP devices

Manual Step-by-Step Dependency Installation

bash windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" MacOS curl -LsSf https://astral.sh/uv/install.sh | sh

The main dependency is the uv tool, so once Python, uv, and Claude or Cline are installed, you're set.

Basic Configuration

Add the following content to your MCP client (e.g., Claude Desktop or Cline) configuration file: Note: If using the automatic installation, this step is not required as it will be configured automatically. Use the default configuration file: json { "mcpServers": { "mcp2tcp": { "command": "uvx", "args": [ "mcp2tcp" ] } } }

Note: After modifying the configuration, you need to restart the Cline or Claude client software.

Configure TCP and commands: Note that the following configuration defaults to COM11 and needs to be adjusted according to your actual setup. yaml

config.yaml

tcp:

TCP server configuration

remote_ip: "127.0.0.1" # Remote IP address port: 9999 # Port number connect_timeout: 3.0 # Connection timeout in seconds receive_timeout: 2.0 # Receive timeout in seconds communication_type: "client" # Communication type, client or server response_start_string: "CMD" # Optional, start string for TCP response, default is OK

commands:

PWM control command

set_pwm: command: "CMD_PWM {frequency}" # frequency is an integer from 0-100, representing the PWM duty cycle need_parse: false # No need to parse the response content data_type: "ascii" # Data type, ascii or hex parameters: - name: "frequency" type: "integer" description: "PWM frequency value (0-100)" required: true prompts: - "Set PWM to maximum (frequency=100)" - "Set PWM to minimum (frequency=0)" - "Please set PWM to {frequency} (an integer between 0-100)" - "Turn off PWM (frequency=0)" - "Set PWM to half (frequency=50)"## Configuration Instructions

Configuration File Location

The configuration file (config.yaml) can be placed at the following locations: User home directory (recommended for personal use) bash

Windows system

C:\Users<username>.mcp2tcp\config.yaml

macOS system

/Users//.mcp2tcp/config.yaml

Linux system

/home//.mcp2tcp/config.yaml

• Applicable scenario: Personal configuration

• You need to create the .mcp2tcp directory: bash

  Windows system (in Command Prompt)

  mkdir "%USERPROFILE%.mcp2tcp"

  macOS/Linux system

  mkdir -p ~/.mcp2tcp

Advanced TCP and Command Configuration

Add custom commands in config.yaml:

Using real TCP yaml

config.yaml

PICO info query command

get_pico_info: command: "CMD_PICO_INFO" # The actual command format, the server will automatically add

need_parse: true # Needs to parse the response content data_type: "ascii" # Data type, ascii or hex prompts: - "Query Pico board information" - "Display development board status"

Specify the configuration file: For example, specify loading the Pico configuration file: Pico_config.yaml json { "mcpServers": { "mcp2tcp": { "command": "uvx", "args": [ "mcp2tcp", "--config", "Pico" // Specify the configuration file name, no need to add _config.yaml suffix ] } } }

To use multiple TCPs, you can add more mcp2tcp services by specifying different configuration file names. If you want to connect to multiple devices, such as a second device: Specify loading the Pico2 configuration file: Pico2_config.yaml json { "mcpServers": { "mcp2tcp2": { "command": "uvx", "args": [ "mcp2tcp", "--config", "Pico2" // Specify the configuration file name, no need to add _config.yaml suffix ] } } }

Testing

Before starting to use it, it is recommended to perform tests to ensure everything works correctly.

1. Start the Test Server

First, start the TCP server in the test directory to simulate the hardware device:

bash

Enter the project directory

cd tests

Start the test server

python tcp_server.py

The server will start locally, listening on port 9999. You will see output similar to this:

TCP server started on 127.0.0.1:9999 Waiting for connections...

Start Client Claude Desktop or Cline

Quick Start from Source Code

1. Install from source bash

Install from source:

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

Create a virtual environment

uv venv .venv

Activate the virtual environment

Windows:

.venv\Scripts\activate

Linux/macOS:

source .venv/bin/activate

Install development dependencies

uv pip install --editable .

If using real TCP yaml

config.yaml

tcp:

TCP server configuration

remote_ip: "127.0.0.1" # Remote IP address port: 9999 # Port number connect_timeout: 3.0 # Connection timeout in seconds receive_timeout: 2.0 # Receive timeout in seconds communication_type: "client" # Communication type, client or server response_start_string: "CMD" # Optional, the start string of the TCP response, default is OK

commands:

PWM control command

set_pwm: command: "CMD_PWM {frequency}" # frequency is an integer from 0-100, representing the PWM duty cycle need_parse: false # Does not need to parse the response content data_type: "ascii" # Data type, ascii or hex parameters: - name: "frequency" type: "integer" description: "PWM frequency value (0-100)" required: true prompts: - "Set PWM to maximum (frequency=100)" - "Set PWM to minimum (frequency=0)" - "Please set PWM to {frequency} (an integer between 0-100)" - "Turn off PWM (frequency=0)" - "Set PWM to half (frequency=50)"

MCP Client Configuration

When using a client that supports the MCP protocol (such as Claude Desktop or Cline), you need to add the following content to the client's configuration file: Direct automatic installation configuration methodConfiguration for Source Code Development

Using Default Demonstration Parameters:

json { "mcpServers": { "mcp2tcp": { "command": "uv", "args": [ "--directory", "your actual path/mcp2tcp", // For example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2tcp" "run", "mcp2tcp" ] } } }

Specifying the Configuration Filename

json { "mcpServers": { "mcp2tcp": { "command": "uv", "args": [ "--directory", "your actual path/mcp2tcp", // For example: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2tcp" "run", "mcp2tcp", "--config", // Optional parameter, specifies the configuration filename "Pico" // Optional parameter, specifies the configuration filename, no need to add _config.yaml suffix ] } } }

Location of Configuration Files

The configuration file (config.yaml) can be placed in different locations. The program will search in the following order:

1. Current Working Directory (Suitable for Development and Testing)

• Path: ./config.yaml
• Example: If you run the program in C:\Projects, it will look for C:\Projects\config.yaml
• Applicable Scenario: Development and testing
• No special permissions required

2. User Home Directory (Recommended for Personal Use)

bash

Windows system

C:\Users<username>.mcp2tcp\config.yaml

macOS system

/Users//.mcp2tcp/config.yaml

Linux system

/home//.mcp2tcp/config.yaml

• Applicable Scenario: Personal configuration

• Requires creating the .mcp2tcp directory: bash

  Windows system (in Command Prompt)

  mkdir "%USERPROFILE%.mcp2tcp"

  macOS/Linux system

  mkdir -p ~/.mcp2tcp

3. System-wide Configuration (Suitable for Multi-user Environments)

bash

Windows system (requires administrator privileges)

C:\ProgramData\mcp2tcp\config.yaml

macOS/Linux system (requires root privileges)

/etc/mcp2tcp/config.yaml

• Applicable Scenario: Shared configuration for multiple users

• Creating the directory and setting permissions: bash

  Windows system (run as Administrator)

  mkdir "C:\ProgramData\mcp2tcp"

  macOS/Linux system (run as root)

  sudo mkdir -p /etc/mcp2tcp sudo chown root:root /etc/mcp2tcp sudo chmod 755 /etc/mcp2tcp

The program will search for the configuration file in the above order and use the first valid one found. Choose an appropriate location based on your needs:

• Development and testing: Use the current directory
• Personal use: It is recommended to use the user home directory (recommended)
• Multi-user environment: Use system-wide configuration (ProgramData or /etc)

3. Running the Server: bash

Ensure the virtual environment is activated

.venv\Scripts\activate

Run the server (using the default config.yaml; in this example, LOOP_BACK simulates TCP, no real TCP or TCP device needed)

uv run src/mcp2tcp/server.py or uv run mcp2tcp

Run the server (using the specified Pico_config.yaml)

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

Documentation

• Installation Guide
• API Documentation
• Configuration Instructions

服务配置

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

来源

• 来源：github
• 链接：https://github.com/mcp2everything/mcp2tcp