MCP2Serial
- docs
- en
# MCP2Serial Installation Guide
## Requirements
- Python 3.11 or higher
- uv package manager
- Serial device (e.g., Arduino, Raspberry Pi Pico)
### Installation
#### For Windows Users
```bash
# Download the installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install.py
# Run the installation script
python install.py
```
#### For MacOS Users
```bash
# Download the installation script
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2serial/main/install_macos.py
# Run the installation script
python3 install_macos.py
```
The installation script will automatically:
- ✅ Check system environment
- ✅ Install required dependencies
- ✅ Create default configuration file
- ✅ Configure Claude Desktop (if installed)
- ✅ Check serial devices
2. Configure serial port and commands:
```yaml
# config.yaml
serial:
port: COM11 # or auto-detect
baud_rate: 115200
commands:
set_pwm:
command: "PWM {frequency}\n"
need_parse: false
prompts:
- "Set PWM to {value}%"
```
3.MCP json Configuration
Add the following to your MCP client (like Claude Desktop or Cline) configuration file, making sure to update the path to your actual installation path:
```json
{
"mcpServers": {
"mcp2serial": {
"command": "uvx",
"args": ["mcp2serial"]
}
}
}
## Configuration
### Configuration File Location
The configuration file (`config.yaml`) can be placed in different locations depending on your needs:
#### 1. Current Working Directory (For Development)
- Path: `./config.yaml`
- Example: If you run the program from `C:\Projects`, it will look for `C:\Projects\config.yaml`
- Best for: Development and testing
- No special permissions required
#### 2. User's Home Directory (Recommended for Personal Use)
```bash
# Windows
C:\Users\YourName\.mcp2serial\config.yaml
# macOS
/Users/YourName/.mcp2serial/config.yaml
# Linux
/home/username/.mcp2serial/config.yaml
```
- Best for: Personal configuration
- Create the `.mcp2serial` directory if it doesn't exist:
```bash
# Windows (in Command Prompt)
mkdir "%USERPROFILE%\.mcp2serial"
# macOS/Linux
mkdir -p ~/.mcp2serial
```
#### 3. System-wide Configuration (For Multi-user Setup)
```bash
# Windows (requires admin rights)
C:\ProgramData\mcp2serial\config.yaml
# macOS/Linux (requires sudo/root)
/etc/mcp2serial/config.yaml
```
- Best for: Shared configuration in multi-user environments
- Create the directory with appropriate permissions:
```bash
# Windows (as administrator)
mkdir "C:\ProgramData\mcp2serial"
# macOS/Linux (as root)
sudo mkdir -p /etc/mcp2serial
sudo chown root:root /etc/mcp2serial
sudo chmod 755 /etc/mcp2serial
```
The program searches for the configuration file in this order and uses the first valid file it finds. Choose the location based on your needs:
- For testing: use current directory
- For personal use: use home directory (recommended)
- For system-wide settings: use ProgramData or /etc
### Serial Port Configuration
Configure serial port parameters in `config.yaml`:
```yaml
serial:
port: COM11 # Example for Windows, might be /dev/ttyUSB0 on Linux
baud_rate: 115200 # Baud rate
timeout: 1.0 # Serial timeout in seconds
read_timeout: 0.5 # Read timeout in seconds
```
### MCP Client Configuration
When using MCP protocol-compatible clients (like Claude Desktop or Cline), add the following to your client's configuration file:
```json
{
"mcpServers": {
"mcp2serial": {
"command": "uvx",
"args": ["mcp2serial"]
}
}
}
```
if you want to develop locally, you can use the following configuration:
```json
{
"mcpServers": {
"mcp2serial": {
"command": "uv",
"args": [
"--directory",
"your project path/mcp2serial", // ex: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2serial"
"run",
"mcp2serial"
]
}
}
}
```
<div align="center">
<img src="../images/client_config.png" alt="Client Configuration Example" width="600"/>
<p>Configuration Example in Claude Desktop</p>
</div>
<div align="center">
<img src="../images/cline_config.png" alt="Cline Configuration Example" width="600"/>
<p>Configuration Example in Cline</p>
</div>
> **Important Notes:**
> 1. Use absolute paths only
> 2. Use forward slashes (/) or double backslashes (\\) as path separators
> 3. Ensure the path points to your actual project installation directory
## Development Steps
1. Clone the repository:
```bash
# Clone the repository
git clone https://github.com/mcp2everything/mcp2serial.git
```
2. Create and activate virtual environment:
```bash
# Navigate to project directory
cd mcp2serial
# Create virtual environment using uv
uv venv .venv
.venv\Scripts\activate
# Install dependencies
uv pip install -r requirements.txt
```
> **Note:** The project will be available on PyPI soon, enabling direct installation via pip.
## Running the Server
```bash
# Ensure you're in the project root
cd mcp2serial
# Activate virtual environment (if not already activated)
.venv\Scripts\activate
# Run the server
uv run src/mcp2serial/server.py
```
## Troubleshooting
1. Serial Port Issues:
- Ensure the device is properly connected
- Verify the correct COM port in Device Manager
- Check baud rate settings match your device
2. MCP Client Issues:
- Verify the path in configuration is absolute and correct
- Ensure uv is installed and in system PATH
- Check if virtual environment is activated
3. Communication Issues:
- Monitor the serial output for debugging
- Check device response format
- Verify command syntax in config.yaml