examples/MCP Client/README.md
This example demonstrates how to use the Model Context Protocol (MCP) with Serial Studio, enabling AI models like Claude to interact with telemetry data and control Serial Studio remotely.
Cmd+,)localhost:7777cd examples/mcp
python3 client.py
✓ Connected to Serial Studio at localhost:7777
✓ Initialized MCP session
Server: Serial Studio
Version: 3.2.7
✓ Available tools (50+):
• api.getCommands: Get list of all available commands
• io.manager.connect: Connect to configured device
• io.manager.disconnect: Disconnect from device
• io.manager.getStatus: Query connection status
• io.driver.uart.setBaudRate: Set UART baud rate
...
✓ Available resources (2):
• serialstudio://frame/current: The most recent telemetry frame
• serialstudio://frame/history: Last 100 telemetry frames
✓ Resource 'serialstudio://frame/current' read successfully
{
"title": "Current Frame",
"groups": [...],
"actions": [...]
}
Model Context Protocol (MCP) is Anthropic's open standard for connecting AI models to external tools and data sources. Serial Studio implements MCP to allow AI assistants like Claude to:
Serial Studio uses a hybrid protocol approach:
// MCP message (has "jsonrpc": "2.0")
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}
// Legacy API (has "type" field)
{
"type": "command",
"id": "1",
"command": "io.manager.getStatus",
"params": {}
}
Every Serial Studio API command is exposed as an MCP tool:
I/O Management:
io.manager.connect - Connect to deviceio.manager.disconnect - Disconnectio.manager.getStatus - Get connection statusio.manager.setBusType - Set bus type (UART, Network, BLE, etc.)UART Configuration:
io.driver.uart.setBaudRate - Set baud rateio.driver.uart.setDataBits - Set data bitsio.driver.uart.setParity - Set parityNetwork Configuration:
io.driver.network.setTcpHost - Set TCP hostio.driver.network.setTcpPort - Set TCP portio.driver.network.setUdpPort - Set UDP portProject Management:
project.openFromFile - Load project fileproject.save - Save projectExport:
csv.export.start - Start CSV exportcsv.export.stop - Stop CSV export...and many more! Use api.getCommands to list all available tools.
Available resources:
serialstudio://frame/current - Latest telemetry frame (JSON)
serialstudio://frame/history - Last 100 frames (JSON array)
Resources support subscription for real-time updates.
Available prompts:
analyze_telemetry - Analyze current telemetry dataSee client.py for a complete example. Key methods:
from mcp_client import MCPClient
client = MCPClient()
client.connect()
client.initialize()
# List all available tools
tools = client.list_tools()
# Call a tool
result = client.call_tool("io.manager.getStatus")
# Read current frame
frame = client.read_resource("serialstudio://frame/current")
# Read frame history
history = client.read_resource("serialstudio://frame/history")
# Connect to Serial Studio
nc localhost 7777
# Initialize MCP session
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"Test","version":"1.0"}}}
# List tools
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
# Call a tool
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"io.manager.getStatus","arguments":{}}}
# Read current frame
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"serialstudio://frame/current"}}
Complete Step-by-Step Guide to Connect Claude Desktop with Serial Studio
Cmd+, / Ctrl+,)A ready-to-use MCP bridge script is included: claude_desktop_bridge.py
The bridge is located at:
examples/MCP Client/claude_desktop_bridge.py
This script connects Claude Desktop (stdio) to Serial Studio's TCP API (port 7777).
Features:
Make it executable (Linux/macOS):
chmod +x claude_desktop_bridge.py
No installation needed - uses Python standard library only.
Locate your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
Edit (or create) the file and add the Serial Studio MCP server:
{
"mcpServers": {
"serial-studio": {
"command": "python3",
"args": ["/absolute/path/to/Serial-Studio/examples/MCP Client/claude_desktop_bridge.py"]
}
}
}
Important: Replace /absolute/path/to/Serial-Studio with the actual path to your Serial Studio repository/installation.
Example (macOS/Linux):
{
"mcpServers": {
"serial-studio": {
"command": "python3",
"args": ["/Users/YOUR_USERNAME/Documents/GitHub/Serial-Studio/examples/MCP Client/claude_desktop_bridge.py"]
}
}
}
Example (Windows):
{
"mcpServers": {
"serial-studio": {
"command": "python",
"args": ["C:\\Users\\YOUR_USERNAME\\Documents\\Serial-Studio\\examples\\MCP Client\\claude_desktop_bridge.py"]
}
}
}
Tip: Use the full absolute path to avoid issues. You can get it with:
# macOS/Linux:
cd examples/MCP\ Client && pwd
# Then append /claude_desktop_bridge.py to the output
# Windows (PowerShell):
cd "examples\MCP Client"; (Get-Location).Path
# Then append \claude_desktop_bridge.py to the output
In Claude Desktop, try asking:
"Can you list all available Serial Studio tools?"
Claude should respond with a list of 182+ tools like:
io.manager.connectio.driver.uart.setBaudRateproject.openFromFileYou can now ask Claude to:
Connect to a device:
"List available serial ports, then connect to the Arduino on the first port with 115200 baud rate"
Read telemetry:
"Read the current telemetry frame from Serial Studio"
Analyze data:
"Read the last 100 frames and tell me if there are any anomalies in the temperature sensor data"
Control Serial Studio:
"Change the baud rate to 9600, disconnect, and reconnect"
Export data:
"Start CSV export and tell me where the file will be saved"
Fix:
~/Library/Logs/Claude/mcp*.log%APPDATA%\Claude\logs\mcp*.log~/.config/Claude/logs/mcp*.logpython3 claude_desktop_bridge.py
# Should show: "✓ Connected to Serial Studio"
# Press Ctrl+C to stop
# Verify file exists
ls -l /path/to/claude_desktop_bridge.py
Fix:
lsof -i :7777 (macOS/Linux) or netstat -ano | findstr :7777 (Windows)nc localhost 7777 (should connect immediately)Fix:
Fix:
"Read serialstudio://frame/current resource"Fix:
python3 in config (not python)python in config and verify Python is in PATH"command": "/usr/bin/python3" or "command": "C:\\Python39\\python.exe"You can modify the bridge script to:
Change host/port:
SERIAL_STUDIO_HOST = "192.168.1.100" # Remote Serial Studio
SERIAL_STUDIO_PORT = 7777
Add reconnection logic:
while True:
try:
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((SERIAL_STUDIO_HOST, SERIAL_STUDIO_PORT))
break
except ConnectionRefusedError:
log("Retrying in 2 seconds...")
time.sleep(2)
Filter messages:
# Only forward specific tool calls
if b'"method":"tools/call"' in line:
sock.sendall(line)
lsof -i :7777initialize firstMCP connections use the same security as the legacy API:
Serial Studio implements MCP 2024-11-05:
initialize handshaketools/list and tools/callresources/list, resources/readresources/subscribe, resources/unsubscribeprompts/list, prompts/getping health check# Connect device via API
client.call_tool("io.manager.connect")
# Read telemetry
frame = client.read_resource("serialstudio://frame/current")
# Verify sensor values
assert frame["groups"][0]["datasets"][0]["value"] < 100
# Read frame history
history = client.read_resource("serialstudio://frame/history")
# Send to Claude for analysis
# "Analyze this telemetry data and identify any anomalies..."
# Change baud rate
client.call_tool("io.driver.uart.setBaudRate", {"value": "115200"})
# Reconnect
client.call_tool("io.manager.disconnect")
client.call_tool("io.manager.connect")
app/src/API/ for implementationThis example follows Serial Studio's dual-licensing:
See main project LICENSE for details.