PlatformIO MCP Server - AI Installation Guide

May 5, 2026 · View on GitHub

This guide is designed for AI agents like Antigravity and Cline to successfully set up the PlatformIO MCP Server.

Prerequisites Check

Before installation, verify these requirements:

1. Check Node.js Version

node --version

Required: Node.js >= 18.0.0

If not installed or version is too old:

macOS: brew install node or download from https://nodejs.org
Linux: Use your package manager or download from https://nodejs.org
Windows: Download from https://nodejs.org

2. Check PlatformIO CLI

pio --version

If not installed, PlatformIO CLI is REQUIRED. Install it:

# Recommended: Install via pip
pip install platformio

# macOS alternative
brew install platformio

# Verify installation
pio --version

Important: The server will start even without PlatformIO installed, but all operations will fail. Users MUST have PlatformIO CLI installed for the server to function.

Installation Steps

Step 1: Navigate to Server Directory

cd /path/to/platformio-mcp

Step 2: Install Dependencies

npm install

What this does:

Installs @modelcontextprotocol/sdk (MCP server framework)
Installs zod (runtime type validation)
Installs all development dependencies
Compiles TypeScript to JavaScript

Expected output: Should complete without errors and create node_modules/ and build/ directories.

Step 3: Build the Server

npm run build

What this does:

Compiles TypeScript source files to JavaScript
Creates the build/ directory with compiled code
Generates type declaration files

Expected output: No errors. The build/ directory should contain compiled .js files.

Step 4: Verify Build

ls build/

Expected files:

index.js (main server file)
platformio.js
types.js
tools/ directory
utils/ directory

Agentic Project Deployment Strategies

If you are developing an embedded C/C++ repository and want to bundle .agents/workflows that rely on this MCP server, you have three primary deployment architectures to ensure the tools are available to any Developer or AI Agent checking out your codebase.

Note on --open-dashboard-on-start: In the examples below, you will see the --open-dashboard-on-start parameter. When passed, this parameter automatically opens the PlatformIO MCP Web Dashboard in your default browser whenever the server starts. This is highly recommended to give developers immediate, visual telemetry of the AI agent's background build and monitor tasks.

1. The `npx` Auto-Execution Approach (Cleanest)

If this package is published to NPM (or your private registry), you do not need to install anything locally. You can simply instruct users to drop this into their global mcp_config.json:

{
  "mcpServers": {
    "platformio": {
      "command": "npx",
      "args": ["-y", "platformio-mcp-server", "--open-dashboard-on-start"]
    }
  }
}

Note: The -y flag forces Node to automatically download, execute, and bridge the MCP background server transparently on-demand without any manual npm install steps.

2. The Native `tools/` Submodule (Embedded Standard)

If you wish to contain the dependency exclusively within your project without relying on global registries:

Add this repository as a submodule: git submodule add <url> tools/platformio-mcp
Create an initialization workflow (.agents/workflows/setup.md) that instructs the Agent: "Navigate to tools/platformio-mcp, run npm install, and npm run build."
Update the mcp_config.json manually or via an installer script mapping the path absolutely:

{
  "mcpServers": {
    "platformio": {
      "command": "zsh",
      "args": [
        "-lic",
        "node /absolute/path/to/your-repo/tools/platformio-mcp/build/index.js --open-dashboard-on-start"
      ]
    }
  }
}

3. The `devDependencies` Integration

If your embedded repository incorporates a package.json (e.g. for React captive portals):

npm install -D github:matthewmcneill/platformio-mcp

This isolates the utility within your node_modules/.bin/, allowing seamless execution securely boxed to the repository context.

Configuration for Cline

Cline requires you to explicitly add the MCP server configuration into its settings file. This is typically found via the VSCode Command Palette (Cmd+Shift+P -> Cline: MCP Servers).

Manual Configuration

Ensure you map the absolute path correctly for your workspace:

{
  "mcpServers": {
    "platformio": {
      "command": "node",
      "args": [
        "/absolute/path/to/platformio-mcp/build/index.js",
        "--open-dashboard-on-start"
      ],
      "env": {}
    }
  }
}

Configuration for Antigravity & Global IDEs

Antigravity requires you to explicitly add the MCP server configuration into its global settings file. This is typically found at ~/.gemini/antigravity/mcp_config.json on macOS/Linux.

Automatic Installer Script

We provide a helper Node.js script to safely map your local clone directly into Antigravity's global footprint. It will intelligently resolve your node binary path and format the JSON. (For the UI dashboard, export PIO_MCP_OPEN_DASH_ON_START=true in your shell environment, or pass --open-dashboard-on-start if modifying the args array).

# From the root of the platformio-mcp repository:
node scripts/install-antigravity.js

Manual Configuration

If manually adding, ensure you map the absolute path correctly:

{
  "mcpServers": {
    "platformio": {
      "command": "zsh",
      "args": [
        "-lic",
        "node /absolute/path/to/platformio-mcp/build/index.js --open-dashboard-on-start"
      ]
    }
  }
}

Configuration for OpenAI Codex CLI

OpenAI Codex CLI reads MCP server definitions from a TOML file at ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml).

Automatic Installer Script

Run the bundled installer to add or update the [mcp_servers.platformio] block in-place — every other section of your config.toml is preserved verbatim:

npx platformio-mcp install --codex
# or the shorter alias:
npx pio-mcp install --codex

After it completes, restart codex and run /mcp to confirm the platformio server is listed.

Manual Configuration

If you prefer to edit the file by hand, append (or merge) this block into ~/.codex/config.toml:

[mcp_servers.platformio]
command = "npx"
args = ["-y", "platformio-mcp", "--open-dashboard-on-start"]

On Windows, use command = "npx.cmd" so Codex resolves the npm shim correctly.

If you've cloned and built the repo locally and want Codex to use that build instead of npx:

[mcp_servers.platformio]
command = "node"
args = ["/absolute/path/to/platformio-mcp/build/index.js", "--open-dashboard-on-start"]

Configuration for Claude Code

Claude Code is Anthropic's official CLI for Claude with native MCP support.

Automatic Configuration

Claude Code supports adding MCP servers directly via its CLI. You can add the PlatformIO MCP server by running:

claude mcp add platformio -- node /absolute/path/to/platformio-mcp/build/index.js --open-dashboard-on-start

Note: Ensure you replace /absolute/path/to/... with the exact path to your cloned repository, and restart Claude Code after adding the server.

Manual Configuration

Alternatively, add the server to ~/.claude/settings.json (global) or .claude/settings.json (project-specific):

{
  "mcpServers": {
    "platformio": {
      "command": "node",
      "args": [
        "/absolute/path/to/platformio-mcp/build/index.js",
        "--open-dashboard-on-start"
      ]
    }
  }
}

Verify installation:

# Start Claude Code - MCP tools load automatically
claude

# You can check available MCP tools with:
/mcp

Usage in Claude Code:

Once configured, interact naturally with your embedded projects:

"Build my PlatformIO project"
"What ESP32 boards are available?"
"Upload firmware to my connected device"
"Search for a JSON parsing library"

Claude Code will automatically use the appropriate MCP tools (mcp__platformio__build_project, etc.).

Troubleshooting

Issue: "Cannot find module '@modelcontextprotocol/sdk'"

Solution:

cd /path/to/platformio-mcp
rm -rf node_modules package-lock.json
npm install

Issue: TypeScript Build Errors

Solution:

npm run build

Check for specific error messages. Common issues:

Missing type definitions: Run npm install
Syntax errors: Check the error message for file and line number

Issue: "PlatformIO CLI not found"

Solution:

# Install PlatformIO
pip install platformio

# Add to PATH if needed
export PATH=$PATH:~/.platformio/penv/bin

# Verify
pio --version

Issue: Permission Errors on macOS/Linux

Solution:

# Make build directory readable
chmod -R 755 build/

# If installing packages fails
sudo npm install -g npm@latest

Validating Installation

Run these commands to verify everything works:

# 1. Check directory structure
ls -la /path/to/platformio-mcp

# 2. Verify dependencies
npm list --depth=0

# 3. Check build output
ls -la build/

# 4. Test PlatformIO CLI
pio --version

# 5. Test board listing (with PlatformIO installed)
pio boards | head -5

All commands should complete without errors.

Quick Reinstall (If Needed)

If something goes wrong, clean reinstall:

cd /path/to/platformio-mcp
rm -rf node_modules build package-lock.json
npm install
npm run build

Understanding the Server

What It Does

The PlatformIO MCP Server provides 12 tools:

list_boards - Discover available development boards
get_board_info - Get specs for a specific board
list_devices - Find connected serial devices
init_project - Create new PlatformIO project
build_project - Compile firmware
clean_project - Remove build artifacts
upload_firmware - Flash firmware to device
upload_filesystem - Upload SPIFFS/LittleFS filesystem image from data/ directory
start_monitor - Get serial monitor command
search_libraries - Find libraries in registry
install_library - Install libraries
list_installed_libraries - List installed libraries

Board-Agnostic Design

The server works with ANY board supported by PlatformIO (1000+ boards). No hardcoded configurations needed. Users just specify the board ID (e.g., "esp32dev", "uno", "nucleo_f401re").

Example Usage Through AI Agents (Antigravity / Cline)

Once configured, users can interact naturally:

"Show me all ESP32 boards"
"Create a new Arduino project for board uno"
"Build the project at /path/to/my-project"
"Upload firmware to my connected device"
"Search for WiFi libraries"

Important Notes for AI Agents

PlatformIO is REQUIRED: The server wraps PlatformIO CLI. Without it, operations will fail with helpful error messages.
Path handling: All project paths are validated and normalized. The server prevents path traversal attacks.
Timeouts:
- Quick operations (list, search): 30 seconds
- Builds: 10 minutes
- Uploads: 5 minutes
Error handling: All errors include troubleshooting hints. Always show error messages to users.
Board IDs are case-sensitive: "ESP32dev" ≠ "esp32dev"
Auto-detection: Ports are auto-detected when possible. Users rarely need to specify them.

Success Criteria

Installation is successful when:

✅ npm install completes without errors
✅ npm run build completes without errors
✅ build/ directory contains compiled JavaScript
✅ node build/index.js starts the server
✅ PlatformIO CLI responds to pio --version

Once all criteria are met, the server is ready for use with Antigravity, Cline, and other AI agents!

PlatformIO MCP Server - AI Installation Guide

Prerequisites Check

1. Check Node.js Version

2. Check PlatformIO CLI

Installation Steps

Step 1: Navigate to Server Directory

Step 2: Install Dependencies

Step 3: Build the Server

Step 4: Verify Build

Testing the Installation

Test 1: Check if Server Starts

Test 2: Verify PlatformIO Integration

Agentic Project Deployment Strategies

1. The `npx` Auto-Execution Approach (Cleanest)

2. The Native `tools/` Submodule (Embedded Standard)

3. The `devDependencies` Integration

Configuration for Cline

Manual Configuration

Configuration for Antigravity & Global IDEs

Automatic Installer Script

Manual Configuration

Configuration for OpenAI Codex CLI

Automatic Installer Script

Manual Configuration

Configuration for Claude Code

Automatic Configuration

Manual Configuration

Troubleshooting

Issue: "Cannot find module '@modelcontextprotocol/sdk'"

Issue: TypeScript Build Errors

Issue: "PlatformIO CLI not found"

Issue: Permission Errors on macOS/Linux

Validating Installation

Quick Reinstall (If Needed)

Understanding the Server

What It Does

Board-Agnostic Design

Example Usage Through AI Agents (Antigravity / Cline)

Important Notes for AI Agents

Success Criteria