Turn your AI assistant into an interactive reference manual for the Parallax Propeller 2.
P2KB MCP connects Claude, Codex, and Cursor to the Propeller 2 Knowledge Base and OBEX (Parallax Object Exchange), giving your AI direct access to PASM2 instructions, Spin2 methods, P2 hardware architecture, and community code objects.
Works on macOS, Windows, Linux, and Raspberry Pi. You'll need Claude Code, Claude Desktop, Cursor, or Codex already installed — P2KB MCP is a server your AI talks to, not a standalone app.
Once installed, just ask your AI in plain English. Here are some examples of what becomes possible:
Your AI becomes an interactive PASM2 manual — ask about any instruction and get syntax, operands, flag effects, encoding details, and usage examples.
"Explain the MOV instruction — what flags does it affect?"
"What's the difference between RDLONG and RDLUT?"
"Show me all the conditional execution prefixes for PASM2."
"How does WAITX work? Can you show an example of a microsecond delay loop?"
Get details on any built-in Spin2 method — parameters, return values, and how to use them.
"How do I use PINSTART to configure a Smart Pin?"
"What are the parameters for the Spin2 SEND method?"
"List all the Spin2 string-handling methods."
"Show me how to set up a serial port in Spin2."
Ask about COGs, HUB memory, Smart Pins, clock configuration, and other hardware topics.
"How does the P2 HUB memory bus work?"
"Explain the Smart Pin modes available for PWM output."
"How many COGs does the P2 have and how do they share resources?"
"What are the P2 clock configuration options?"
Search and discover the ~113 community objects in the Parallax Object Exchange — drivers, libraries, and examples contributed by the P2 community.
"Find me an OBEX object for driving WS2812B LEDs."
"Are there any I2C sensor drivers in the OBEX?"
"Show me what motor control objects are available."
"What OBEX objects has Jon McPhalen published?"
Combine knowledge areas — your AI can pull from multiple parts of the knowledge base in a single conversation.
"I need to bit-bang SPI in PASM2. Show me the relevant instructions and then find an OBEX object I could use instead."
"Help me understand how to launch a PASM2 COG from Spin2 — what Spin2 methods and PASM2 instructions are involved?"
Three steps: download, install, connect. Pick your platform:
| Platform | Guide |
|---|---|
| macOS | Getting started on macOS |
| Windows | Getting started on Windows |
| Linux / Raspberry Pi | Getting started on Linux |
Each guide covers Claude Code, Claude Desktop, Cursor, and Codex — the install is the same for all of them, only the last step differs. Part 1 is all you need; it stands on its own and stops at a working setup.
What you download: a small platform-specific archive — e.g. p2kb-mcp-vX.X.X-darwin-arm64.tar.gz on Apple Silicon, p2kb-mcp-vX.X.X-windows-amd64.zip on Windows. It contains just the binary for your machine plus the docs.
The separate container-tools-p2kb-mcp-vX.X.X.tar.gz package exists for a specific niche: users who run multiple MCP servers and want them co-located under a shared /opt/container-tools/ tree with a unified installer, shared mcp.json, automatic backup/rollback on updates, and Claude Code lifecycle hooks. It ships binaries for all platforms in one archive along with an install.sh script.
Unless you are already using the container-tools framework for other MCPs, skip this — the standard install above is simpler and does the same job for a single MCP. If it does apply to you, it is described in the Advanced section at the end of your platform guide.
Ask your AI a question only the knowledge base can answer:
"What does the PASM2 RDFAST instruction do?"
If P2KB MCP is connected, the answer cites the knowledge base. If your AI hedges or talks about the Propeller 1, it is not connected yet — see the troubleshooting section in your platform guide.
P2KB MCP is an MCP server — a small program that runs locally on your machine. When your AI tool needs Propeller 2 information, it queries the MCP server, which fetches and caches content from the P2 Knowledge Base on GitHub. You don't need to download any documentation manually; the server handles it automatically.
The knowledge base covers:
| Area | Content |
|---|---|
| PASM2 | All assembly instructions with syntax, encoding, flag effects, and examples |
| Spin2 | Built-in methods with parameters, return values, and usage |
| Architecture | COG, HUB, Smart Pins, and hardware documentation |
| Guides | Quick reference cards and getting-started material |
| OBEX | ~113 community code objects — drivers, libraries, and demos |
Take it further: when PNut-TS (the cross-platform Spin2/PASM2 compiler) and PNut-Term-TS (the P2 downloader and debug terminal) are installed on your machine, your AI assistant becomes a full pair programmer — not just a reference, but an active collaborator that can write, compile, download, and debug P2 code alongside you.
With all three tools available, you give high-level engineering intent and your AI handles the rest:
"I need a FIFO to queue data from one COG to another. Create it as a standalone Spin2 object."
"Write regression tests for the FIFO — test empty, full, overflow, and underflow conditions."
"Run the regression tests on the P2 and make sure the FIFO is completely working."
"Now add a PASM2 driver COG that pushes sensor readings into the FIFO at 10 kHz."
Your AI looks up the correct PASM2 instructions and Spin2 methods from the Knowledge Base, writes the code, compiles with pnut-ts, downloads to the P2 with pnut-term-ts, reads the debug output, and iterates until the tests pass — all autonomously within a single conversation.
Or start from the hardware side — hand your AI a new peripheral and let it plan the architecture:
"Here's the datasheet for the BME280 sensor. What interface options does it support, and what data rates can we achieve?"
"Which P2 features are the best fit for talking to this device — Smart Pin SPI, bit-banged, or something else?"
"Show me the performance I could achieve with each approach, given P2 clock and instruction timing."
"Write up an architecture plan for the driver."
Your AI researches the hardware documentation online, maps the interface requirements against P2 capabilities from the Knowledge Base — Smart Pin modes, instruction cycle timing, streamer bandwidth — and produces an engineering plan showing what's achievable before writing a single line of code.
Then you wire up the hardware and hand it back to your AI:
"I've wired the BME280 to the P2 — SDA is on pin 40, SCL on pin 41, power on 3.3V. Build the driver and verify it reads valid sensor data."
From there, your AI generates the code with the correct pin assignments, compiles, downloads to the P2, and validates against real hardware — closing the loop from datasheet to working driver.
| Tool | What It Provides |
|---|---|
| P2KB MCP | Accurate PASM2, Spin2, and hardware knowledge so the AI writes correct P2 code |
| PNut-TS | Cross-platform Spin2/PASM2 compiler (Windows, macOS, Linux, RPi) |
| PNut-Term-TS | P2 downloader + serial terminal + debug display (Windows, macOS, Linux, RPi) |
PNut-TS and PNut-Term-TS are command-line tools that Claude Code, Codex, and Cursor can invoke directly. No special configuration is needed beyond having them on your PATH.
Tip: After installing PNut-TS and PNut-Term-TS, ask your AI to learn them:
"Run
pnut-ts --helpandpnut-term-ts --helpso you know how to use the P2 compiler and terminal tools."
This teaches your AI the full command syntax, flags, and options so it can use both tools effectively throughout your session.
PNut-Term-TS includes a headless mode designed specifically for AI agent and CI workflows. This lets your AI download code to the P2, capture serial/debug output, and determine when a run is complete — all without a GUI:
# Download to RAM, run until the program prints END_SESSION
pnut-term-ts --headless -r program.bin --end-marker
# Download to RAM, run for 30 seconds, then exit
pnut-term-ts --headless -r program.bin --timeout 30
# Wait for a custom end phrase in the output
pnut-term-ts --headless -r test.bin --end-marker "TEST_DONE"
# Download to FLASH for persistent storage
pnut-term-ts --headless -f program.bin --timeout 10In headless mode, all serial and debug output from your Spin2 program is captured to a log file. When the run completes, your AI reads the log, sees what worked and what didn't, makes code corrections, and recompiles — a full compile-download-test-fix loop running autonomously on real hardware.
- Changelog — Version history
- API Reference — MCP tool specifications (for developers)
- Testing & Coverage — Test strategy and metrics
MIT License — see LICENSE for details.
- P2 Knowledge Base — Documentation source
- OBEX — Parallax Object Exchange
- Propeller 2 — The microcontroller
- Model Context Protocol — MCP specification
Iron Sheep Productions, LLC