Skip to main content
Glama
nt-mcp-server

nt-mcp-server

by Mzzj114

nt-mcp-server

Listed on mcpservers.org

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 DS port 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 list

Claude Code

claude mcp add --scope project nt -- uvx --from git+https://github.com/Mzzj114/nt-mcp-server.git nt-mcp-server
claude mcp list

OpenCode

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

nt_connect

Start the NT4 client and wait for a connection. Defaults to 127.0.0.1:5810; choose team_number or server_ip/server_port. Conflicting targets and re-targeting a running client are refused; disconnect first. Returns the resolved target or timeout diagnostics.

nt_disconnect

Stop the client, tear down persistent subscriptions and request active recordings to close.

nt_connection_info

Return connection state, remote peers, resolved target and package version.

nt_read_topics

Read one or more exact topics. Returns {connected, values: {topic: value}}; unknown topics have null values.

nt_get_topic_info

Return one topic's name, NT type and properties, or null if unknown.

nt_write_topics

Publish an updates map, including a single-entry map. Returns per-topic results and warnings. strict_type_check=True refuses known type mismatches. Writes are not atomic.

nt_list_topics

Discover live topic names with optional prefix, regex and wildcard filters.

nt_sample

Observe selected updates for duration seconds (up to 60). Defaults to output="summary"; output="samples" returns timestamp/value rows. Returns samples keyed by topic, rows, total_rows and truncated.

nt_start_subscription

Start a persistent in-memory subscription and return its subscription_id. buffer_size bounds retained events; oldest events are discarded when full.

nt_poll_subscription

Read buffered events; clear=True clears them after polling.

nt_stop_subscription

Stop the subscription and free its resources.

nt_start_recording

Start an NDJSON recording and immediately return its recording_id and path for a human-controlled test window.

nt_stop_recording

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

nt_list_recordings

List available files, newest first, with file metadata and persisted capture timing when available.

nt_get_recording_info

Return capture duration, NT event span, sample count, file metadata and a sorted topic list. prefix, regex and wildcard filter topic discovery; topic_limit defaults to 100 (maximum 1000). topic_count describes the whole file; matching_topic_count, topics_returned and topics_truncated describe discovery.

nt_query_recording

Query selected topics. Returns {recording_id, topics, rows, total_rows, truncated}. Defaults to output="samples"; output="summary" returns statistics under the same topics key. Supports start (inclusive), end (exclusive), last_seconds and sample_interval.

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 from requirements.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-server

Equivalent Python entry point:

python -m nt_mcp_server

For RobotPy simulation, start the simulator from the robot project:

python -m robotpy sim

Then 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

nt_get(topic) / nt_get_multiple(topics)

nt_read_topics(topics=[...]); values are always keyed by topic

nt_set(topic, value) / nt_set_multiple(updates)

nt_write_topics(updates={topic: value}); results/warnings are always keyed by topic

nt_get_info(topic)

nt_get_topic_info(topic)

nt_subscribe(output="summary") or output="samples"

nt_sample(output=...); defaults to summary and has no file mode

nt_subscribe(output="file")

nt_start_recording(...), then nt_stop_recording(recording_id)

nt_get_history(topic, ...)

nt_query_recording(topics=[topic], ...); read topics[topic]

nt_subscribe_offline(format=...)

nt_query_recording(output=...)

nt_list_topics_offline(...)

nt_get_recording_info(...); read topics and discovery counts

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_subscribe output rework: the format parameter was removed and replaced by output, which defaults to "file". Callers that passed format= must switch to output=. 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 by limit, max_rows, and a 60,000-character ceiling.

  • Offline tools return receipts: nt_get_history now includes rows / total_rows / truncated; nt_subscribe_offline returns {recording_id, topics, rows, total_rows, truncated}. Clipping is never silent.

  • nt_connect target guards: an ambiguous target (both team_number and a non-default server_ip) is rejected before any state change, and re-targeting a running client is refused — call nt_disconnect first.

  • nt_connection_info gained target and version: target is the resolved connect target (null before the first connect); version is the installed package version.

License

This project is under MIT License.

Available Tools

18 tools
nt_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

    B3.4/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: connection management, get/set operations, topic listing, subscriptions (both transient and persistent), and recording access. No overlapping functionality.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.
      84 npm
      10
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      3
      28 npm
      2
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      MCP 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.
      43
      54 PyPI
      1
      MIT