DavidMenting/picotool-mcp-server

Picotool MCP Server

An MCP (Model Context Protocol) server that provides Claude Code with capabilities to interact with Raspberry Pi Pico devices (RP2040/RP2350) through the picotool command-line tool.

✨ Features

• 🔍 Device Information: Query connected Pico devices for detailed hardware and firmware info
• 📁 Binary Analysis: Analyze UF2, ELF, and BIN files without flashing to device
• 🧩 Pin Mapping: Extract pin assignment information from firmware
• 🔄 Device Reboot: Reboot devices between application and BOOTSEL modes programmatically
• 🎯 Device Selection: Filter devices by USB bus, address, VID/PID, or serial number
• 🔧 Version Checking: Get picotool version information for troubleshooting
• 🗂️ Partition Management: View RP2350 partition table information and layout
• 🏛️ Multi-Architecture: Support for ARM and RISC-V cores on RP2350 devices
• ⚡ Fast Integration: Built with uv for lightning-fast dependency management
• 🛡️ Robust Error Handling: Graceful handling of disconnected devices and file errors
• 📊 Comprehensive Data: Access to device info, build metadata, memory layout, and more

🚀 Quick Start

Prerequisites

• Python 3.10+
• uv for dependency management
• picotool installed and available in PATH

Installation

# Clone the repository
git clone https://github.com/DavidMenting/picotool-mcp-server.git
cd picotool-mcp-server

# Install dependencies with uv
uv sync

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "picotool": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/picotool-mcp-server",
        "run",
        "python",
        "-m",
        "picotool_mcp_server"
      ]
    }
  }
}

Note: Replace /absolute/path/to/picotool-mcp-server with the actual path to this repository.

Standalone Usage

You can also run the server directly:

uv run python -m picotool_mcp_server

🛠️ Available Tools

picotool_info

Get comprehensive information about connected Pico devices or analyze binary files. Can automatically force running devices into BOOTSEL mode - no physical button press required!

Parameters

Examples

Auto-detect running device and get info (most common use case):

{
  "force": true,
  "all": true
}

Get basic info from device already in BOOTSEL mode:

{
  "basic": true
}

Get comprehensive device information:

{
  "all": true
}

Analyze a firmware file:

{
  "target": "/path/to/firmware.uf2",
  "pins": true,
  "build": true
}

Force a running device to provide info (useful for development):

{
  "force": true,
  "all": true
}

Query a specific device by serial number:

{
  "serial": "20C110CE49017709",
  "device": true,
  "pins": true
}

Sample Output

Partition 1
 Program Information
  name:          my-project
  version:       1.0.0
  description:   My Pico Project
  features:      USB stdin / stdout
  target chip:   RP2350
  image type:    ARM Secure

 Fixed Pin Information
  0:             UART0 TX
  1:             UART0 RX
  2:             I2C0 SDA
  3:             I2C0 SCL

 Device Information
  type:          RP2350
  revision:      A2
  flash size:    16384K
  current cpu:   ARM

picotool_reboot

Reboot connected Pico devices to application mode or BOOTSEL mode for development workflows.

Parameters

Examples

Reboot to BOOTSEL mode (for firmware flashing):

{
  "usb_mass_storage": true,
  "force": true
}

Reboot back to application mode:

{}

Reboot all connected devices:

{
  "all_devices": true
}

Reboot to specific partition (RP2350):

{
  "partition": "1",
  "force": true
}

Reboot with specific CPU (RP2350):

{
  "cpu": "RISC-V",
  "usb_mass_storage": true
}

picotool_version

Get picotool version information for troubleshooting and diagnostics.

Parameters

This tool takes no parameters - it simply returns the installed picotool version.

Example

{}

Sample Output

picotool v2.0.0 (d4c9a39)

picotool_partition_info

Get partition table information from RP2350 devices. RP2040 devices don't have partition tables.

Parameters

Examples

Get full partition table:

{}

Show partition info for ARM secure family:

{
  "family_id": "rp2350-arm-s"
}

Force a running device to show partition info:

{
  "force": true
}

Sample Output

un-partitioned_space :  S(rw) NSBOOT(rw) NS(rw), uf2 { absolute }
partitions:
  0(A)       00002000->00201000 S(rw) NSBOOT(rw) NS(rw), id=0000000000000000, "A", uf2 { rp2350-arm-s, rp2350-riscv }, arm_boot 1, riscv_boot 1
  1(B w/ 0)  00201000->00400000 S(rw) NSBOOT(rw) NS(rw), id=0000000000000001, "B", uf2 { rp2350-arm-s, rp2350-riscv }, arm_boot 1, riscv_boot 1

With family ID specified:

Family ID 'rp2350-arm-s' can be downloaded in partition 0:
  00002000->00201000

📋 Supported Devices

• RP2040: Original Raspberry Pi Pico, Pico W, and compatible boards
• RP2350: Raspberry Pi Pico 2 and compatible RP2350-based boards

🔧 Development

Setup Development Environment

# Install development dependencies
uv sync --dev

# Install pre-commit hooks (optional)
pre-commit install

Code Quality

# Format code
uv run black .

# Lint code  
uv run ruff check .

# Type checking
uv run mypy src/

Testing

# Run tests (when implemented)
uv run pytest

# Test the server manually
uv run python -c "
import asyncio
from src.picotool_mcp_server.picotool import PicotoolWrapper

async def test():
    picotool = PicotoolWrapper()
    version = await picotool.version()
    print(f'Picotool version: {version}')

asyncio.run(test())
"

🐛 Troubleshooting

Common Issues

Server fails to start:

• Ensure picotool is installed and in your PATH
• Verify Python 3.10+ is being used
• Check that uv is installed

No devices found:

• Connect your Pico device in BOOTSEL mode (hold BOOTSEL while plugging in)
• Verify device appears in system (check USB device list)
• Try picotool info directly to confirm device detection

Permission errors:

• On Linux, you may need to add udev rules for the Pico device
• Ensure your user has permission to access USB devices

Debug Logging

The server logs important events. Check Claude Desktop's MCP server logs:

macOS: ~/Library/Logs/Claude/mcp-server-picotool.log

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (uv run black . && uv run ruff check .)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Related Projects

• picotool: The official Raspberry Pi Pico command-line tool
• MCP: Model Context Protocol specification
• Claude Code: AI-powered code editor with MCP support

Built with ❤️ for the Raspberry Pi Pico community