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
    }
  }
}

Verify with opencode mcp list from the project root: the nt server should show as connected.

Development

• Python 3.14.0 venv in .venv; deps installed from requirements.txt (fastmcp==3.4.7, pyntcore==2026.2.2).
• Tests: uv run pytest tests/ -v

License

This project is under MIT License.