mcp-tensorboard

A minimal, stdio-based MCP server that exposes TensorBoard Data Server queries as MCP tools.

This project does not run the TensorBoard web UI. Instead, it starts TensorBoard’s data server subprocess (the Rust binary) and queries it via gRPC using TensorBoard’s Python APIs.

The data server approach was taken because it was significantly faster than a “pure Python” approach that iterates events.out.tfevents.* files directly. In one real-world case, loading a ~1GB event file via the pure Python approach took ~2 minutes.

Protocol: this server attempts to implement MCP protocol revision 2025-03-26 (Zed-compatible). See the spec: https://modelcontextprotocol.io/specification/2025-03-26

AI-friendly outputs (compact points)

Most time-series tools return compact point arrays to reduce response size:

• Scalars / scalar-tensors: {"points": [[step, value], ...]}
• Histograms: {"points": [[step, values], ...]} where values is the underlying numeric array for that step (large; prefer distributions below)
• Image series: {"points": [[step, blob_key], ...]} where blob_key can be fetched via tensorboard-get_image
• Optional wall_time is omitted by default and can be included via include_wall_time=true

Notes:

• step and wall_time are not rounded.
• Numeric values are rounded to float_precision=5 by default (where applicable).

Features

• Stdio JSON-RPC 2.0 transport (one JSON object per line).
• Starts TensorBoard data server for a given --logdir.
• Tool-based API for common queries:
  • list runs
  • list tags (scalars / tensors / histograms / images / distributions)
  • fetch scalar and tensor time-series (compact points)
  • fetch histogram series (compact points; can still be large)
  • fetch distribution series (compressed histograms; small and AI-friendly)
  • fetch image series (blob keys) + fetch individual images (MCP image content)

Installation

Running without publishing (uvx from git)

You can run the tool without publishing to PyPI using uvx:

uvx --from git+https://github.com/jchacks/mcp-tensorboard mcp-tensorboard --logdir /path/to/tensorboard/logdir --debug

If you prefer SSH:

uvx --from git+ssh://git@github.com/jchacks/mcp-tensorboard.git mcp-tensorboard --logdir /path/to/tensorboard/logdir --debug

Installation (editable)

From the repo root:

pip install -e .

With dev tools:

pip install -e ".[dev]"

Running

The server is a stdio server: it reads JSON lines from stdin and writes JSON lines to stdout.

Run using the console script:

mcp-tensorboard --logdir /path/to/tensorboard/logdir --debug

Or run as a module:

python -m mcp_tensorboard --logdir /path/to/tensorboard/logdir --debug

You can also set the environment variable:

export TENSORBOARD_LOGDIR=/path/to/tensorboard/logdir
mcp-tensorboard --debug

Tool names

The tool names are:

• tensorboard-list_runs
• tensorboard-list_scalar_tags
• tensorboard-get_scalar_series
• tensorboard-get_scalar_series_batch
• tensorboard-get_scalar_last
• tensorboard-list_tensor_tags
• tensorboard-get_tensor_series
• tensorboard-list_histogram_tags
• tensorboard-get_histogram_series
• tensorboard-list_distribution_tags (alias of histogram tags)
• tensorboard-get_distribution_series
• tensorboard-list_image_tags
• tensorboard-get_image_series
• tensorboard-get_image

Notes on images

Image fetching is a two-step process to keep responses small:

1. tensorboard-get_image_series returns points as [[step, blob_key], ...]
2. tensorboard-get_image takes a blob_key and returns MCP image content (content: [{type:"image", mimeType, data}]) where data is base64-encoded image bytes.

Protocol (JSON-RPC over stdio)

Messages are one JSON object per line.

List tools

Request:

{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}

Response:

{"jsonrpc":"2.0","id":"1","result":{"tools":[{"name":"tensorboard-list_runs","description":"...","inputSchema":{...}}],"nextCursor":null}}

Call a tool

Request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "tensorboard-list_runs",
    "arguments": {}
  }
}

Response (shape):

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      { "type": "text", "text": "{\"runs\":[\".\",\"runA\"]}" }
    ],
    "structuredContent": { "runs": [".", "runA"] },
    "isError": false
  }
}

Examples

1) List runs

{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"tensorboard-list_runs","arguments":{}}}

2) List scalar tags for a run

{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"tensorboard-list_scalar_tags","arguments":{"run":"."}}}

3) Fetch a scalar series (last 200 points)

Returns points as [[step, value], ...] (optionally [[step, value, wall_time], ...] if include_wall_time=true).

{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"tensorboard-get_scalar_series","arguments":{"run":".","tag":"loss","max_points":200}}}

4) Fetch multiple scalar series in one call

Returns pointsByTag with compact points per tag.

{"jsonrpc":"2.0","id":"4","method":"tools/call","params":{"name":"tensorboard-get_scalar_series_batch","arguments":{"run":".","tags":["loss","accuracy"],"max_points":200}}}

5) Fetch the last scalar value

{"jsonrpc":"2.0","id":"5","method":"tools/call","params":{"name":"tensorboard-get_scalar_last","arguments":{"run":".","tag":"loss"}}}

6) List tensor tags

{"jsonrpc":"2.0","id":"6","method":"tools/call","params":{"name":"tensorboard-list_tensor_tags","arguments":{"run":"."}}}

7) Fetch tensor “series” (scalar tensors only)

Returns points as [[step, value], ...] for scalar tensors only.

{"jsonrpc":"2.0","id":"7","method":"tools/call","params":{"name":"tensorboard-get_tensor_series","arguments":{"run":".","tag":"some_tensor","max_points":200}}}

8) List histogram (and distribution) tags

Histogram tags are also used for distributions. You can list them via either tool:

{"jsonrpc":"2.0","id":"8","method":"tools/call","params":{"name":"tensorboard-list_histogram_tags","arguments":{"run":"."}}}

Or (alias):

{"jsonrpc":"2.0","id":"8b","method":"tools/call","params":{"name":"tensorboard-list_distribution_tags","arguments":{"run":"."}}}

9) Fetch histogram series (raw)

Histogram points can be large. The response is compact but the per-step values array may still be big:

• points: [[step, values], ...] where values is the underlying numeric array for that step

{"jsonrpc":"2.0","id":"9","method":"tools/call","params":{"name":"tensorboard-get_histogram_series","arguments":{"run":".","tag":"weights","max_points":50}}}

10) Fetch distribution series (compressed histograms; recommended for AI)

This compresses histogram buckets into fixed basis points (defaults to TensorBoard’s “normal” set): (0, 668, 1587, 3085, 5000, 6915, 8413, 9332, 10000)

Response shape:

• bps: the basis points (x-axis labels)
• data: per-step {step, values} where values[i] corresponds to bps[i]

{"jsonrpc":"2.0","id":"10","method":"tools/call","params":{"name":"tensorboard-get_distribution_series","arguments":{"run":".","tag":"weights","max_points":50}}}

11) List image tags

{"jsonrpc":"2.0","id":"11","method":"tools/call","params":{"name":"tensorboard-list_image_tags","arguments":{"run":"."}}}

12) Fetch image series (blob keys)

Returns points as [[step, blob_key], ...].

{"jsonrpc":"2.0","id":"12","method":"tools/call","params":{"name":"tensorboard-get_image_series","arguments":{"run":".","tag":"samples","max_points":10}}}

13) Fetch a single image (MCP image content)

Use a blob_key returned by tensorboard-get_image_series.

{"jsonrpc":"2.0","id":"13","method":"tools/call","params":{"name":"tensorboard-get_image","arguments":{"blob_key":"PUT_BLOB_KEY_HERE"}}}

Repository layout (current)

• mcp_tensorboard/server.py — stdio JSON-RPC server entrypoint
• mcp_tensorboard/tools.py — tool implementations + data server lifecycle
• mcp_tensorboard/tool_args.py — argument unpacking + type validation decorator
• tests/ — unit tests (fake provider)

Development

Run tests:

pytest

Format/lint (if installed in dev extras):

ruff check .

Troubleshooting

• No runs found: ensure --logdir points at the directory containing runs / event files.
• Import error: tensorboard: install dependencies (pip install -e .).
• Data server fails to start: verify TensorBoard is installed and compatible with your environment.