RedPitayaCore-MCP
It exposes a narrow, safety-gated MCP interface for Red Pitaya diagnostics and bounded RX operations, with no TX or live lifecycle execution.
Report configured mode, target, and capabilities without hardware I/O (
rp_profile).Read bounded HTTP device/app metadata (
rp_device_diagnostics).Run fixed read-only SSH diagnostics for OS/model/process/app/FPGA evidence (
rp_system_diagnostics).Probe TCP reachability by connect/close without sending bytes (
rp_connection_probe).Report local socket state and requested RX settings without device/TX readback (
rp_connection_status).Plan or mock-simulate app start/stop; live start/stop is always blocked (
rp_app_lifecycle).Open RX, make bounded float32 I/Q reads, and close RX when explicitly permitted and acknowledged (
rp_rx_connect,rp_rx_read,rp_rx_disconnect).Defaults to mock mode; live RX requires
RP_ALLOW_RX=trueandacknowledge_side_effects=true; no TX, FPGA programming, MMIO, or ILA capture is exposed in this schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RedPitayaCore-MCP Check my Red Pitaya's connection status and show its profile"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RedPitayaCore-MCP
A local MCP server for safe Red Pitaya diagnostics, RX access, and bounded
offline FPGA development from Claude Code.
It targets an operator-managed STEMlab 125-14 running official Red Pitaya OS
3.00-57 with Pavel Demin sdr_transceiver 1.0-20260302 build cbecbdd4.
Those values are a compatibility target, not facts inferred from an open port or
device response.
The server starts in deterministic mock mode, with no target host and no hardware traffic. Its live surface is deliberately narrow: bounded metadata and connection diagnostics, optional fixed read-only SSH diagnostics, and explicitly enabled RX control/data. A separate local FPGA surface can inspect and edit an explicitly selected HDL workspace, plan named register operations, run an operator-configured Vivado toolchain, inspect generated artifacts, and produce ILA Tcl plans. It has no dedicated tool for loading an FPGA image, accessing live MMIO, capturing an ILA, or transmitting RF, and its generated Tcl requests none of those actions.
Safety boundary
RP_MODE=mockis the default and requires no hardware.Live mode requires an explicit unicast IPv4
RP_HOSTchosen by the operator.Live RX requires
RP_ALLOW_RX=trueat process startup andacknowledge_side_effects=trueonrp_rx_connect.RX connect and disconnect change device state: role 0 resets tuning/rate, role 1 resets the RX FIFO, and closing control resets tuning.
The upstream TCP protocol has no acknowledgement.
connecteddoes not prove the server accepted a role or setting.RP_ALLOW_LIFECYCLE=trueenables lifecycle execution in mock mode only. Live start and stop remain blocked because startup may program the FPGA and stop changes global controller ownership.All sample values, including mock data, are uncalibrated units.
This MCP has no TX path and does not force the board's outputs off. Actual hardware TX state remains
unknown_not_read; another client may control it.Local FPGA permissions are independent of
RP_MODE. Enabling project writes or builds in mock mode changes local files or starts Vivado. Trusted HDL, XDC, simulator and vendor code can perform arbitrary actions with the build user's OS, network and device access, outside this MCP's dedicated transport adapters.rp_fpga_hardware_planis always non-executing. No environment variable turns bitstream loading, register writes, or TX into executable operations.
Read the protocol boundary, provenance, and security policy before enabling live RX. See the FPGA development guide before enabling local writes or builds.
Related MCP server: Sierra Chart MCP
Requirements
Python 3.11 or newer
Claude Code with local stdio MCP support
Optional for live system diagnostics: the system
sshclient, existing key authentication, and a verifiedknown_hostsentryOptional for real local FPGA builds: a licensed Linux Vivado installation and an operator-selected absolute executable path
The dependency mcp>=1.30,<2 is intentional. It uses the official Python SDK
1.x maintenance line and avoids silently adopting an unreviewed major version.
Install
Clone the public repository and create an isolated environment:
git clone https://github.com/theerayutbo/RedPitayaCore-MCP.git
cd RedPitayaCore-MCP
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .When using uv, install exactly the reviewed lock file included in the clone:
uv sync --frozenRun the server directly with either entry point:
.venv/bin/redpitayacore-mcp
# or
.venv/bin/python -m redpitayacore_mcpThe stdio transport reserves stdout for MCP protocol messages. Operational logs must go to stderr; do not wrap the command with scripts that print to stdout.
Add to Claude Code
For safe mock mode at project scope:
claude mcp add --scope project --transport stdio \
-e RP_MODE=mock \
redpitaya-core -- \
/absolute/path/to/RedPitayaCore-MCP/.venv/bin/redpitayacore-mcpEnvironment options must appear before the server name. Replace the absolute
path with your clone location. You can also adapt
examples/claude-mcp.json as a project .mcp.json.
The committed example is mock-only and contains no credentials or local address.
Confirm registration, then ask Claude Code to call rp_profile or
rp_connection_status. These remain local mock operations.
Configuration
Configuration belongs to the server process, not MCP tool arguments.
Variable | Default | Meaning |
|
|
|
| unset | Required explicit unicast IPv4 in live mode |
|
| SDR TCP port |
|
| HTTP metadata port |
|
| I/O timeout from 0.1 through 10 seconds |
|
| Operator permission for live RX state changes |
|
| Restores RX sample order, as needed on the tested board. |
|
| Permission for mock lifecycle execution only |
| unset | Enables optional fixed read-only SSH diagnostics |
|
| SSH port |
| unset | Absolute existing local FPGA workspace directory |
|
| Allows bounded HDL/XDC writes inside the project root |
|
| Allows real local Vivado jobs; also requires project-write permission |
| unset | Absolute path to the operator-selected Vivado executable |
|
| Local build timeout from 0.1 through 3,600 seconds |
The sample .env.example is documentation; the server reads its
process environment and does not need an environment file. Do not commit a live
address, username, credentials, private key, or captured device output.
For a live board, prefer user scope so target details stay out of a shared project configuration:
claude mcp add --scope user --transport stdio \
-e RP_MODE=live \
-e 'RP_HOST=<BOARD_IPV4>' \
-e RP_ALLOW_RX=false \
redpitaya-core -- \
/absolute/path/to/RedPitayaCore-MCP/.venv/bin/redpitayacore-mcpReplace <BOARD_IPV4> before running that command. Start with RX disabled. This
registration permits safe diagnostics only. If you
later enable live RX, do so in your user-local configuration after completing
hardware acceptance. SSH is optional and unavailable until RP_SSH_USER is set;
it uses fixed read-only commands, strict host-key checking, and existing key
authentication. The project does not store keys or passwords.
MCP tools
The server exposes 25 tools: the original nine SDR/device tools and 16 offline
FPGA-development tools. The FPGA tools are prefixed rp_fpga_.
Device and RX tools
Tool | Behavior |
| Reports configured mode and operator-reported compatibility target |
| Reads bounded HTTP application/device metadata |
| Connects to the configured SDR port, sends no bytes, and closes |
| Runs fixed read-only OS/app/process/FPGA SSH checks; unavailable unless configured |
| Plans |
| Opens RX control/data with validated frequency and rate; live use requires both permission gates |
| Reads bounded little-endian float32 I/Q; defaults to 2,048 samples and 8 previews |
| Closes RX sockets; closing control resets tuning upstream |
| Reports local socket state and explicitly unknown hardware TX state |
FPGA development tools
Tool | Behavior |
| Reports workspace/toolchain availability and explicit hardware limits |
| Reads the same fixed SSH FPGA/overlay/installed-file evidence without MMIO |
| Shows the source-pinned instance-1 register profile; performs no access |
| Validates one named, width-limited read/write proposal; never executes it |
| Lists blockers and interlocks for image load, register write, or TX burst |
| Lists bounded HDL, XDC, and artifact paths below |
| Reads bounded UTF-8 RTL/XDC and returns its SHA-256 |
| Creates or SHA-guardedly replaces bounded RTL/XDC when locally enabled |
| Hashes a bounded |
| Reads bounded |
| Binds local hashes to a claimed part/source revision in an unapproved proposal |
| Dry-runs by default; real trusted-code execution also needs explicit per-call acknowledgement |
| Returns state and a bounded output tail for an owned job |
| Cancels an owned job and terminates its process group on POSIX |
| Reads the timing, utilization, or DRC report from an owned job |
| Generates exact-net ILA insertion Tcl; does not rebuild, deploy, or capture |
Artifact inspection checks extension, size, and SHA-256 only. It does not parse the format or prove the target board. A manifest is not signed or approved, and its claimed source revision is not verified against the artifact. A successful Vivado process does not by itself establish timing closure, correct logic, board compatibility, or safe RF behavior.
Source replacement uses an advisory lock for cooperating RedPitayaCore-MCP processes and an expected SHA-256. External editors and build tools must be quiescent during the write; this is not a filesystem-wide compare-and-swap.
Run real build jobs on an isolated host or container with no route to the Red
Pitaya and no USB, JTAG, or other board-device access. In addition to the two
operator environment permissions, every dry_run=false call must set
acknowledge_trusted_code=true. That acknowledgement records the caller's
understanding that HDL, XDC, simulation, and vendor initialization are executable
input; it is not a sandbox or independent approval. Build results cannot prove
that external hardware activity did or did not occur.
rp_rx_read caps acquisition at 8,192 complex samples and returned previews at
32 samples. A successful probe or connection is reachability evidence, not
device, OS, application, build, FPGA-image, or protocol identity.
Recommended live acceptance order
Keep
RP_ALLOW_RX=falseand runrp_profile.Run
rp_device_diagnosticsandrp_connection_probe.If separately configured, run
rp_system_diagnostics; review OS, app/process, and FPGA state as independent evidence. Unknown remains unknown.Have the operator start the installed app using their established device procedure. This project does not automate bitstream loading. Do not open the board's web UI or call any
/bazaarURL while the app is in use: on the tested board/bazaar?appsand/bazaar?helpstopped the running app within 0.5 s.Verify the device model, OS release, installed app build, FPGA state, and listening service outside this MCP server.
Enable RX only after reviewing the side effects and local RF setup. Call
rp_rx_connectwith explicit acknowledgement, make a bounded read, then callrp_rx_disconnect.
Tested on real hardware. Release 0.2.1 passed 63 of 63 acceptance checks on a
STEMlab 125-14 v1.0 running Red Pitaya OS 3.00-57 and sdr_transceiver 1.0-20260302 on
2026-11-02: HTTP and SSH diagnostics, TCP probe, RX at all six sample rates, disconnect
and reconnect, and four safety refusals. It also passed 134 of 134 extended checks: the
local FPGA tools, sustained RX up to 100,000 S/s, and recovery from failures. Above that
rate, reads work but continuity is not guaranteed. TX is not part of this server, and real
Vivado builds were not tested. See docs/VALIDATION.md for the results
and limits. To repeat them on your own idle board, run scripts/live_acceptance.py and
scripts/extended_acceptance.py.
Offline FPGA quick start
Copy or point RP_PROJECT_ROOT at an existing local workspace. A small
self-checking counter example is included in examples/fpga-demo:
export RP_MODE=mock
export RP_PROJECT_ROOT="$PWD/examples/fpga-demo"
export RP_ALLOW_PROJECT_WRITE=false
export RP_ALLOW_LOCAL_BUILD=false
redpitayacore-mcpStart with rp_fpga_project_info, rp_fpga_read_source, and an
rp_fpga_build call using dry_run=true. Simulation uses simple_counter.sv
and tb_counter.sv. The XDC only declares the example clock timing; it contains
no STEMlab package-pin assignments. Synthesis can exercise the flow, but
implementation/bitstream generation needs a reviewed board constraint set and
may correctly fail DRC with this example. Real execution additionally requires
both local permission flags and an absolute RP_VIVADO_EXECUTABLE on a licensed
supported Linux host. Full setup and call examples are in
docs/FPGA_DEVELOPMENT.md.
Development
Install development dependencies:
python -m pip install -e '.[dev]'Run the local checks:
pytest
ruff check .
ruff format --check .
mypy src
bandit -q -r src
pip-audit
python -m buildThe test suite includes protocol vectors, mock behavior, loopback TCP/HTTP fixtures, safety failures, and a real MCP stdio client path. CI repeats the repository checks. These checks do not replace hardware validation. See validation evidence and precise limits.
Project status and limitations
No real STEMlab was contacted during development.
No dedicated MCP TX tool or live hardware mutation adapter exists.
Live app start/stop is always blocked.
Live FPGA programming, MMIO/register access, ILA capture, and TX remain unimplemented. Hardware-plan tools cannot enable them.
The generated Vivado flow is experimental. Vivado was not installed in the development environment. Toolchain tests cover generated Tcl and bounded fixture processes, not real synthesis, implementation, timing closure, bitstream validity, ILA insertion, or board compatibility.
Configured local FPGA workspaces/builds require POSIX descriptor features. Default mock startup does not require a workspace; Windows operation is unvalidated.
HDL, constraints, and testbenches passed to a build are trusted local code, not an OS sandbox. The generated flow does not source existing project Tcl hooks or request hardware programming, but other trusted code run by Vivado can use the build process's OS, network, and device permissions.
TCP roles and settings have no protocol acknowledgement.
Metadata and open ports do not guarantee the requested hardware/software target.
I/Q units are uncalibrated.
Compatibility is limited to the source-verified subset described in docs/PROTOCOL.md.
License
MIT. See LICENSE.
Available Tools
9 toolsrp_app_lifecycleCDestructive
Plan lifecycle URLs or simulate mock lifecycle. Live start/stop always blocked.
Inputs: action (required), dry_run. Returns: object
rp_connection_probeBRead-onlyIdempotent
TCP connect/close with no selector. Briefly occupies server accept; no identity proof.
Inputs: no named parameters. Returns: object
rp_connection_statusBRead-onlyIdempotent
Report local sockets/requested RX settings. No device setting or TX state readback.
Inputs: no named parameters. Returns: object
rp_device_diagnosticsARead-onlyIdempotent
Read bounded HTTP app metadata. Cannot verify running app/OS/FPGA identity.
Inputs: no named parameters. Returns: object
rp_profileARead-onlyIdempotent
Report configured capabilities and operator-reported target, without hardware I/O.
Inputs: no named parameters. Returns: object
rp_rx_connectADestructive
Open RX only, resetting RX config/FIFO. Live requires RP_ALLOW_RX and acknowledgement.
Requires exclusive app ownership. Closing resets tuning/rate. No server ACK/readback. sample_rate: 20000, 50000, 100000, 250000, 500000 or 1250000 samples/second.
Inputs: sample_rate, frequency_hz, acknowledge_side_effects. Returns: object
rp_rx_disconnectADestructive
Close owned RX sockets. Server resets RX tuning/rate; never opens TX sockets.
Inputs: no named parameters. Returns: object
rp_rx_readBDestructive
Consume bounded buffered float32 IQ and return summary/preview; not calibrated RF.
Inputs: sample_count, preview_samples. Returns: object
rp_system_diagnosticsARead-onlyIdempotent
Read OS/model/process/app/FPGA evidence with optional fixed-command SSH; no writes.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools are clearly separated by resource and action: diagnostics, connection checks, app lifecycle, and RX lifecycle are distinct. The diagnostics/status cluster (rp_profile, rp_device_diagnostics, rp_system_diagnostics, rp_connection_probe, rp_connection_status) has some conceptual overlap, but the descriptions clarify the boundaries and constraints.
All tools use a consistent rp_ prefix and snake_case, making the set predictable. The pattern is mostly rp_<domain>_<action>, though several diagnostic tools are noun-like rather than strict verb_noun, which is a minor deviation.
Nine tools is well-scoped for a hardware diagnostics and RX-control server. Each tool covers a distinct capability area without an excessive or thin surface.
The surface covers profile/diagnostics, connection checks, app lifecycle planning, and RX connect/read/disconnect. Minor gaps remain around live lifecycle operation and TX or deeper RX configuration/readback, but the core safe diagnostic and RX workflows are covered.
Maintenance
Related MCP Connectors
Run verified read-only code tools: quant diagnostics + agent-ops preflight, no source exposure.
Read-only verifier for 25 ProofRelay MCP tools and non-confidential evidence bundles.
Read-only Remote MCP for externally grounded AI agent trust receipts.
Read-only cited financial datasets, bounded research queries and source diagnostics.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for diagnosing H7-TOOL hardware via Modbus, USB HID, and Lua diagnostics, exposing only safe read operations.20-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to observe and inspect Sierra Chart chartbooks, charts, studies, drawings, and data, read diagnostics, and apply validated configuration changes via a local bridge, without any order execution or trading features.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables investigation of devices, model breaches and analyst incidents from an MCP host through a bounded set of read-only tools, with operator-controlled profiles and a fixed operation inventory. Writes, PCAP export, email and HTTP transport are excluded, and responses are minimized and escaped before entering model context.16 npm3Apache 2.0
- AlicenseAqualityCmaintenanceEnables MCP clients on macOS to perform bounded read-only filesystem operations and a narrow allowlist of process diagnostics over STDIO or authenticated loopback Streamable HTTP. It excludes file writes, arbitrary shell access, GUI/browser automation, and remote relay.10MIT