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+, on macOS)localhost:7777cd "examples/MCP Client"
python3 client.py
✓ Connected to Serial Studio at localhost:7777
✓ Initialized MCP session
Server: Serial Studio
Version: <your Serial Studio version>
✓ Available tools (...):
• api.getCommands: Get list of all available commands
• io.connect: Open the configured connection
• io.disconnect: Close the current connection
• io.getStatus: Query connection status
• io.uart.setBaudRate: Set UART baud rate
• project.template.list: List bundled project templates
...
✓ Available resources (2):
• serialstudio://frame/current: Current Frame
The most recent telemetry frame received
• serialstudio://frame/history: Latest Frame
The latest telemetry frame, as a JSON array
✓ 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.getStatus",
"params": {}
}
Every Serial Studio API command is exposed as an MCP tool:
I/O Management:
| Command | Description |
|---|---|
io.connect | Connect to device |
io.disconnect | Disconnect |
io.getStatus | Get connection status |
io.setBusType | Set bus type (UART, Network, BLE, etc.) |
UART Configuration:
| Command | Description |
|---|---|
io.uart.setBaudRate | Set baud rate |
io.uart.setDataBits | Set data bits |
io.uart.setParity | Set parity |
Network Configuration:
| Command | Description |
|---|---|
io.network.setRemoteAddress | Set remote host |
io.network.setTcpPort | Set TCP port |
io.network.setUdpRemotePort | Set UDP remote port |
io.network.setUdpLocalPort | Set UDP local port |
Project Management:
| Command | Description |
|---|---|
project.exportJson | Read the active project as JSON |
project.template.list / project.template.apply | Browse and apply bundled starters |
project.group.add / project.dataset.add / project.workspace.add | Edit the in-memory project |
project.frameParser.setCode | Update frame parser source |
Export:
| Command | Description |
|---|---|
csvExport.setEnabled | Toggle CSV export |
csvExport.close | Close the current CSV file |
mdf4Export.setEnabled (Pro) | Toggle MDF4 export |
...and many more! Send tools/list over MCP (or
{"command": "api.getCommands"} over the legacy JSON protocol) to
enumerate the complete surface.
Available resources:
serialstudio://frame/current - Latest telemetry frame (JSON)
serialstudio://frame/history - Latest telemetry frame, as a JSON array
serialstudio://frame/current, wrapped in a single-element arrayResources support subscription for real-time updates.
Available prompts:
analyze_telemetry - Analyze current telemetry dataSee client.py for a complete example. Key methods:
from 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.getStatus")
# Read current frame
frame = client.read_resource("serialstudio://frame/current")
# Read the latest frame as a single-element array
frame_array = 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.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+, on macOS)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 tools like:
io.connectio.uart.setBaudRateproject.openYou 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:
"Subscribe to the current telemetry frame and tell me if the temperature sensor readings look anomalous"
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.connect")
# Read telemetry
frame = client.read_resource("serialstudio://frame/current")
# Verify sensor values
assert frame["groups"][0]["datasets"][0]["value"] < 100
# Subscribe to real-time frame updates
client.send_request("resources/subscribe", {"uri": "serialstudio://frame/current"})
# Send each incoming frame to Claude for analysis
# "Analyze this telemetry data and identify any anomalies..."
# Change baud rate
client.call_tool("io.uart.setBaudRate", {"baudRate": 115200})
# Reconnect
client.call_tool("io.disconnect")
client.call_tool("io.connect")
app/src/API/ for implementationThis example follows Serial Studio's dual-licensing:
See main project LICENSE for details.