nt-mcp-server
Summary: This MCP server connects AI agents to FRC NetworkTables, enabling inspection, monitoring, writing, and offline analysis of robot telemetry.
Connect to a live NT4 server (default
127.0.0.1:5810) by IP/port or FRC team number, and disconnect from it.Inspect connection state, resolved target, remote peers, and package version.
Read single or multiple topic values, and fetch topic metadata (name, NT type, properties).
Write one or many topic values with optional strict type checking, returning per-topic results/warnings.
Discover live topics using prefix, regex, and wildcard filters.
Sample live updates over a duration window, with optional decimation, change-only filtering, and summary (min/max/mean/last) or raw-sample output.
Create persistent subscriptions with bounded buffers, poll them later, and stop them when done.
Start and stop NDJSON recordings for interactive test windows, returning recording IDs and receipts.
List recordings and get recording metadata (duration, sample count, topic count, file size, timestamps).
Query recorded history for one topic or multiple prefixes, with start/end/last_seconds, limits, decimation, and summary or sample output.
List unique topic names within recordings with optional filters.
Note: The supplied schema exposes the older 20-tool surface (e.g., nt_get, nt_set, nt_subscribe, nt_get_history, nt_subscribe_offline, nt_list_topics_offline), whereas the README documents the consolidated 16-tool 0.3.0 surface (nt_read_topics, nt_write_topics, nt_sample, nt_query_recording, nt_start_recording/nt_stop_recording).
Provides tools for reading, writing, and monitoring FRC NetworkTables data, allowing interaction with FIRST Robotics Competition simulators and real robot network tables.
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., "@nt-mcp-server Read the current value of /SmartDashboard/robotPosition"
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.
nt-mcp-server
What is a MCP?
The Model Context Protocol (MCP) is a standard way for AI agents to use external tools and data. The concept is established by Anthropic researchers in the end of 2024. For more information, see https://modelcontextprotocol.io/.
This server exposes FIRST Robotics Competition (FRC) NetworkTables through MCP, so a coding agent can inspect telemetry, diagnose robot behavior, and test values without manually copying data between the robot, dashboards, and code.
It works with a local RobotPy simulation by default and can also connect to a real robot.
How do I use AI while connecting to the Robot Wifi?
Obviously Robot Wifi doesn't provide Internet access, so you can't call LLM. The key is to use TWO network adapters: one for the Robot Wifi, another for Internet access. The first network adapter is usually the one inside your device that you always use to go online. For the second one, your laptop may have a Ethernet port, you can therefore connect a Ethernet cable to the
DSport of the robot radio. In other cases, you may want a USB-to-Ethernet adapter or a USB wireless network adapter. The connections should be ready to go now. Rarely you need to configure the routing table of your device to explicitly guide traffic targeting the robot IP to the correct network adapter.
Register with an agent
The package can run directly from Git with uvx, so no checkout or pre-built virtual environment is required. Install uv first, then use the setup for your agent.
Codex
codex mcp add nt -- uvx --from git+https://github.com/Mzzj114/nt-mcp-server.git nt-mcp-server
codex mcp listClaude Code
claude mcp add --scope project nt -- uvx --from git+https://github.com/Mzzj114/nt-mcp-server.git nt-mcp-server
claude mcp listOpenCode
Add the server to the project's opencode.jsonc:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"nt": {
"type": "local",
"command": [
"uvx",
"--from",
"git+https://github.com/Mzzj114/nt-mcp-server.git",
"nt-mcp-server"
],
"enabled": true
}
}
}Verify the connection with opencode mcp list.
Related MCP server: ftc-mcp
Tools
The server exposes 16 tools (13 live + 3 offline). Every live response includes a connected flag. Reads and writes have separate tools.
Live tools
Tool | Description |
| Start the NT4 client and wait for a connection. Defaults to |
| Stop the client, tear down persistent subscriptions and request active recordings to close. |
| Return connection state, remote peers, resolved target and package version. |
| Read one or more exact |
| Return one topic's name, NT type and properties, or null if unknown. |
| Publish an |
| Discover live topic names with optional |
| Observe selected updates for |
| Start a persistent in-memory subscription and return its |
| Read buffered events; |
| Stop the subscription and free its resources. |
| Start an NDJSON recording and immediately return its |
| Close a recording and return a compact receipt with timing, row count, topic names and truncation flags, without sample values. |
Live sampling, subscriptions, recordings and recording queries share prefixes, exact topics, regex and wildcard selectors. Entries within a list are ORed; different selector kinds are ANDed. At least one selector is required. A bare prefixes=["/"] is allowed for recordings, but refused for inline sampling and recording queries unless another selector narrows it.
nt_sample blocks for its fixed window and returns inline results. For an interactive test, call nt_start_recording, perform the test, then call nt_stop_recording. Use the returned ID for offline analysis after the file closes.
Read value metadata
nt_read_topics(topics=["/limelight/tv", "/missing"], include_metadata=True) adds a
metadata map alongside the existing values map. Omitting the flag (or
passing False) preserves the compact {connected, values} response.
{
"connected": true,
"values": {"/limelight/tv": 0.0, "/missing": null},
"metadata": {
"/limelight/tv": {
"type": "double",
"valid": true,
"local_time_us": 123456789,
"server_time_us": 987654321
},
"/missing": {
"type": null,
"valid": false,
"local_time_us": null,
"server_time_us": null
}
}
}Every requested topic appears in both maps. type is the NT value's storage
type, preserving int versus double, float, and array types such as
int[] and double[]; it is not inferred from the JSON value. Custom topic
type labels (such as json or struct schemas) and properties are available
through nt_get_topic_info. valid describes the NT value before JSON
normalization: raw values still normalize to null but can be valid with
type: "raw". Missing/unassigned values have valid: false and null
value, type and timestamps, including advertised topics with no value yet.
Disconnected reads retain {connected: false, error: ...} with either flag.
Both timestamps are integer microseconds for the pinned pyntcore version.
local_time_us is the value creation/update timestamp in this client's NT
clock domain (nt::Now()); server_time_us is that timestamp in the NT
server's clock domain. Neither should be assumed to be Unix/wall-clock time
or robot FPGA time. Nonpositive NT timestamps (including unknown server
time), and the pinned library's server-time placeholder 1 for locally
created values, are returned as null, even when the value is valid. Comparing to a
robot-side clock may require robot-side instrumentation. See the
NT Value implementation
and the installed ntcore._now() documentation for the NT clock time base.
Each topic's value, type, validity and timestamps come from one atomic NT value snapshot. The batch reads topics sequentially; it is not an atomic snapshot across topics. These are cached current values and do not wait for a fresh publication. A timestamp provides evidence of a value update; it does not acknowledge execution of a command sent through another topic.
Offline recording tools
Tool | Description |
| List available files, newest first, with file metadata and persisted capture timing when available. |
| Return capture duration, NT event span, sample count, file metadata and a sorted topic list. |
| Query selected topics. Returns |
The offline directory defaults to NT_RECORDINGS_DIR or ./recordings; output_dir overrides it. Omitting recording_id selects the most recently modified recording. Queries return the resolved ID. The MCP tools refuse to inspect a recording still being written by this server; a separate CLI recorder must also be stopped before analysis.
For one topic's history:
nt_query_recording(
topics=["/SmartDashboard/Swerve/Pose X"],
recording_id="nt-record-...ndjson",
last_seconds=5,
output="summary",
)Inline sampling and offline queries are bounded by per-topic limit, total max_rows (default 5000, maximum 5000) and a 60,000-character ceiling. Summary statistics describe retained rows; rows / total_rows / truncated report reduction explicitly. Offline total_rows counts matching events before limits and decimation; live total_rows counts events after sampling/change filters and before output clipping. last_seconds uses the latest NT event timestamp, which can differ from the capture clock.
Each new recording has a sibling .meta.json sidecar. capture_duration_seconds measures capture time; event_span_seconds measures the range of NT last-change timestamps, including older immediate values. Legacy files without sidecars report duration_source="event_span".
The nt-recorder CLI remains available independently of MCP, including --team N for robot address lookup. Recordings are local to the server host; no robot-side changes are needed.
Development
Python 3.14.0 venv in
.venv; deps installed fromrequirements.txt(fastmcp==3.4.7,pyntcore==2026.2.2).Tests:
uv run pytest tests/ -v
To run the mcp server by yourself from a local checkout, start the stdio MCP server with:
uv run nt-mcp-serverEquivalent Python entry point:
python -m nt_mcp_serverFor RobotPy simulation, start the simulator from the robot project:
python -m robotpy simThen use nt_connect with its defaults to connect to 127.0.0.1:5810.
For a real robot, connect the development machine to the robot network and call nt_connect with team_number. If the agent also needs Internet access, use separate network adapters—for example, Wi-Fi for Internet and Ethernet or a USB network adapter for the robot—and configure routing if needed.
Release notes
0.3.0 — consolidated tool surface
The exposed MCP surface changes from 20 to 16 tools. Restart the MCP server/client to refresh tool discovery. These are breaking name and argument changes:
Previous call | Replacement |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Schemas describe every parameter and enforce output enums, absolute topic names, non-empty batches, positive sampling intervals, row budgets, port ranges and filename-only recording IDs. Offline reader functions in nt_recorder retain their Python API.
0.2.0 — breaking changes
nt_subscribeoutput rework: theformatparameter was removed and replaced byoutput, which defaults to"file". Callers that passedformat=must switch tooutput=. In"file"mode the response is a compact receipt (recording path, row count, topic list) with no sample values; inline modes ("summary","samples") are bounded bylimit,max_rows, and a 60,000-character ceiling.Offline tools return receipts:
nt_get_historynow includesrows/total_rows/truncated;nt_subscribe_offlinereturns{recording_id, topics, rows, total_rows, truncated}. Clipping is never silent.nt_connecttarget guards: an ambiguous target (bothteam_numberand a non-defaultserver_ip) is rejected before any state change, and re-targeting a running client is refused — callnt_disconnectfirst.nt_connection_infogainedtargetandversion:targetis the resolved connect target (nullbefore the first connect);versionis the installed package version.
License
This project is under MIT License.
Available Tools
18 toolsnt_connectB
Start the NT4 client and wait for a live connection.
Inputs: identity, server_ip, server_port, team_number. Returns: object
nt_connection_infoC
Return {"connected": bool, "connections": [...]}.
Inputs: no named parameters. Returns: object
nt_disconnectA
Stop the NT4 client and tear down any persistent subscriptions.
Inputs: no named parameters. Returns: object
nt_getB
Return the JSON-normalized value of topic.
Response: {"connected": bool, "value": jsonable | null} when
connected, or {"connected": false, "error": "..."} when
disconnected.
Inputs: topic (required). Returns: object
nt_get_historyB
Return event history for one topic from a recording.
last_seconds selects the most recent N seconds of the recording.
sample_interval and format="summary" behave like live
nt_subscribe.
Inputs: topic (required), end, limit, start, +5 more. Returns: result
nt_get_infoC
Return metadata for topic.
Response: {"connected": bool, "info": {...} | null}.
Inputs: topic (required). Returns: object
nt_get_multipleB
Return values for every requested topic.
Response: {"connected": bool, "values": {topic: value}}.
Inputs: topics (required). Returns: object
nt_get_recording_infoC
Return metadata about a recording.
Includes duration, total sample count, topic count, file size and timestamps.
Inputs: output_dir, recording_id. Returns: object
nt_list_recordingsA
List available NDJSON recordings in the output directory.
Each entry includes id, path, size_bytes, modified
(Unix float) and modified_iso (UTC ISO-8601).
Inputs: output_dir. Returns: result
nt_list_topicsB
Return topic names, filtered by prefix, regex, and/or wildcard.
Response: {"connected": bool, "topics": [...]}.
Inputs: regex, prefix, wildcard. Returns: object
nt_list_topics_offlineC
List unique topic names in a recording, optionally filtered.
Inputs: regex, prefix, wildcard, output_dir, +1 more. Returns: result
nt_poll_subscriptionA
Return buffered samples for a persistent subscription.
Response:
{"connected": bool, "samples": {topic: [{"time", "value"}, ...]}}.
clear=True empties the buffer after reading.
Inputs: subscription_id (required), clear. Returns: object
nt_setA
Publish value to topic.
Response: {"connected": bool, "ok": bool, "warning": str | null}.
strict_type_check=True refuses mismatched writes instead of only
warning about them.
Inputs: topic (required), value (required), strict_type_check. Returns: object
nt_set_multipleB
Write every {topic: value} pair.
Response:
{"connected": bool, "results": {topic: bool}, "warnings": {topic: str | null}}.
Inputs: updates (required), strict_type_check. Returns: object
nt_start_subscriptionA
Open a persistent subscription and start collecting samples.
Response:
{"connected": bool, "subscription_id": str, "started": bool}.
Use nt_poll_subscription to read the buffered samples in later
turns, and nt_stop_subscription to tear it down.
Inputs: prefixes (required), buffer_size, subscription_id. Returns: object
nt_stop_subscriptionB
Stop a persistent subscription and free its resources.
Inputs: subscription_id (required). Returns: object
nt_subscribeA
Sample value updates under prefixes for duration seconds.
Response: {"connected": bool, "samples": {topic: [...] | summary}}.
sample_interval decimates events to one per topic per interval.
change_only skips numeric changes at or below the threshold.
format="summary" returns min/max/mean/last per topic.
Inputs: prefixes (required), format, duration, change_only, +1 more. Returns: object
nt_subscribe_offlineB
Return events for every topic under prefixes from a recording.
last_seconds selects the most recent N seconds. sample_interval
decimates per-topic samples, and format="summary" returns
min/max/mean/last per topic.
Inputs: prefixes (required), end, limit, start, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool serves a distinct purpose: connection management, get/set operations, topic listing, subscriptions (both transient and persistent), and recording access. No overlapping functionality.
All tools use a consistent 'nt_' prefix and follow a verb_noun pattern (e.g., nt_get, nt_set_multiple, nt_list_topics, nt_start_subscription). Naming is uniform and predictable.
With 18 tools, the set is slightly larger than typical but justified by the breadth of NetworkTables features (live/offline, subscriptions, recordings). It remains manageable and not overwhelming.
The tool surface covers all major operations: connect/disconnect, get/set (individual and bulk), topic listing, both transient and persistent subscriptions, and comprehensive recording access (list, info, history, offline subscription). No obvious gaps.
Maintenance
Related MCP Connectors
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.84 npm10MIT
- AlicenseAqualityDmaintenanceMCP server that injects verified FTC documentation and code examples into AI assistants, enabling teams to write correct, competition-ready Java robot code through natural language.328 npm2MIT
- AlicenseCqualityCmaintenanceMCP server for Inductive Automation Ignition, enabling AI assistants to browse and write tags, query history and alarms, manage projects, and deploy Perspective views through natural language.4354 PyPI1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for AI agents to inspect and control ROS2 graphs, enabling topic listing, node info, service calls, parameter management, and pub/echo without manual ROS2 CLI usage.12MIT