MCP 服务器

nt-mcp-server

MCP server for reading, writing, and monitoring FRC NetworkTables data, enabling AI agents to interact with a robot's NetworkTables over the NetworkTables protocol.

README

nt-mcp-server

A standalone MCP server for reading, writing, and monitoring FRC NetworkTables data. It lets an AI agent talk to a robot's network tables over the NetworkTables protocol. The primary target is the local RobotPy sim (python -m robotpy sim on 127.0.0.1:5810).

pinned dependencies (fastmcp==3.4.7, pyntcore==2026.2.2).

Run the server

uv run nt-mcp-server

Or, equivalently, from a checkout without uv's shim:

python -m nt_mcp_server

The server runs on stdio, which is how MCP clients (like opencode) talk to it.

Connect to RobotPy sim NetworkTables

The sim must be running before the server can read or write anything useful. Start it from its own project and venv:

cd <path-to-try-robotpy> && .venv\Scripts\activate && python -m robotpy sim

The server connects to 127.0.0.1:5810 by default, which is where the sim listens.

Connect to Real Robot NetworkTables

For most cases, just record NetworkTables and use the mcp to analyze the recordings.

If you want to connect to a real robot's NetworkTables in real time, you need to have 2 network adapters on you device: one for Internet and the other for robot communication. One approach is to use your wireless adapter to connect to the wifi and use a ethernet cable to connect to the robot. Alternatively, you get a USB Network Adapter as the second adapter. In ethier cases, you may need to configure your device's network routing.

Record NetworkTables to NDJSON (offline)

The nt-recorder CLI connects to a live NT4 server and writes value events to a timestamped .ndjson file. It runs on the dev laptop and reads NT from the sim or robot; no robot-side changes are needed.

uv run nt-recorder --prefixes /SmartDashboard/ --output-dir recordings

Options:

--prefixes — topic prefixes to subscribe to (default: /)
--output-dir — directory for output files (default: ./recordings)
--duration — record for N seconds, then exit (default: run until Ctrl+C)
--team — connect via team number instead of server IP/port
--server-ip / --server-port — NT4 server address (default: 127.0.0.1:5810)
--identity — client identity string (default: nt-recorder)
--quiet — suppress status output to stderr

Output files are named nt-record-<YYYY-MM-DDTHHMMSSZ>.ndjson (no colons, Windows-safe). Each line is {"time": float, "topic": str, "value": jsonable}. Exit codes: 0 clean, 1 connection failure, 2 disk/IO error.

Tools

The server exposes 17 tools (13 live + 4 offline). Every live tool response includes a connected flag.

Live tools

Tool	Description
`nt_connect`	Start the NT4 client and wait for a live connection. Returns `{"connected": bool, "status": "connected" \| "not connected"}`.
`nt_disconnect`	Stop the NT4 client and tear down persistent subscriptions. Returns `{"connected": false, "status": "disconnected"}`.
`nt_connection_info`	Return connection state: `{"connected": bool, "connections": [...]}`.
`nt_get`	Return the JSON-normalized value of one topic. Response: `{"connected": bool, "value": jsonable \| null}`.
`nt_get_multiple`	Return every requested topic. Response: `{"connected": bool, "values": {topic: value}}`.
`nt_get_info`	Return topic metadata. Response: `{"connected": bool, "info": {name, type_str, properties} \| null}`.
`nt_set`	Publish a value. Response: `{"connected": bool, "ok": bool, "warning": str \| null}`. Add `strict_type_check=True` to refuse type mismatches.
`nt_set_multiple`	Write every `{topic: value}` pair. Response: `{"connected": bool, "results": {...}, "warnings": {...}}`.
`nt_list_topics`	List topic names, filtered by `prefix`, `regex`, and/or `wildcard`. Response: `{"connected": bool, "topics": [...]}`.
`nt_subscribe`	Sample updates under prefixes for `duration` seconds. Response: `{"connected": bool, "samples": {topic: [...] \| summary}}`. Supports `sample_interval`, `change_only`, and `format="summary"`.
`nt_start_subscription`	Open a persistent subscription. Response: `{"connected": bool, "subscription_id": str, "started": bool}`.
`nt_poll_subscription`	Read buffered samples from a persistent subscription. Response: `{"connected": bool, "samples": {topic: [...]}}`.
`nt_stop_subscription`	Stop a persistent subscription. Response: `{"connected": bool, "stopped": bool}`.

Offline recording tools

Tool	Description
`nt_list_recordings`	List recordings. Each entry includes `id`, `path`, `size_bytes`, `modified` (Unix float), and `modified_iso` (UTC ISO-8601).
`nt_get_recording_info`	Return duration, total sample count, topic count, and file metadata for a recording.
`nt_get_history`	Return event history for one topic. Supports `last_seconds`, `sample_interval`, and `format="summary"`.
`nt_list_topics_offline`	List unique topic names in a recording, filtered by `prefix`, `regex`, and/or `wildcard`.
`nt_subscribe_offline`	Return events for every topic under prefixes. Supports `last_seconds`, `sample_interval`, and `format="summary"`.

The offline tools read from the directory set by the NT_RECORDINGS_DIR environment variable (defaults to ./recordings). Recordings are local-only — the recorder runs on the dev laptop and reads NT from the sim/robot; no robot-side changes are needed.

Register in any agent

The server is a uvx-runnable package from git, so any MCP client can launch it without a local checkout or a pre-built venv. Run it on demand:

uvx --from git+https://github.com/Mzzj114/nt-mcp-server.git nt-mcp-server

Or install the console script once and run it anywhere:

uv tool install "git+https://github.com/Mzzj114/nt-mcp-server.git"
uvx nt-mcp-server

Add this entry to your agent's MCP config (shown here as opencode's project-level opencode.jsonc):

{
  "mcp": {
    "nt": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/Mzzj114/nt-mcp-server.git",
        "nt-mcp-server"
      ],
      "enabled": true
    }
  }
}