TensorBoard Event Query MCP Server

Overview

TensorBoard Event Query MCP Server exposes TensorBoard event files through a simple, programmatic Model Context Protocol (MCP) server. Instead of parsing event files ad-hoc in scripts or opening a full TensorBoard instance, this server indexes event files and exposes structured endpoints for runs, tags, scalars, histograms and raw events. It makes it easier to query metrics, fetch time/step-series, and integrate event data into custom dashboards, CI checks, or lightweight analysis tools.

This approach is useful when you need repeatable, automatable access to training logs across many experiments or machines. The MCP server is optimized for quick lookups and streaming access to logged values so you can debug models faster, compare runs programmatically, and build bespoke visualizations without the overhead of launching the full TensorBoard web UI.

Features

• Index TensorBoard event files (.tfevents) and discover runs automatically
• Query scalar series by run and tag (time/step/value)
• List runs and available tags (scalars, histograms, images, text)
• Retrieve raw event payloads for debugging or custom processing
• Lightweight MCP-compatible HTTP API suitable for programmatic access
• Optional file-watch mode to auto-update indices when event files change
• CLI for quickly launching a local server; Docker-friendly

Installation / Configuration

Clone and run the server locally:

# Clone the repository
git clone https://github.com/Alir3z4/tb-query.git
cd tb-query

# (Optional) Create virtualenv
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the MCP server pointing to a directory with event files
python -m tb_query.server --logdir /path/to/event/files --host 0.0.0.0 --port 8080

Typical CLI flags:

--logdir   /path/to/event/files    # directory containing TensorBoard event files
--host     127.0.0.1               # bind address
--port     8080                    # HTTP port
--watch                          # enable file system watch to reload on changes
--cache-size N                   # optional cache size for indexed data

Run with Docker:

docker build -t tb-query .
docker run -p 8080:8080 -v /local/events:/events tb-query \
  --logdir /events --port 8080 --watch

Adjust configurations in your orchestration or systemd unit if running in production.

Available Resources

• GitHub repository: https://github.com/Alir3z4/tb-query
• Source code: explore server, parser, and CLI modules in the repo
• Example dataset: use any directory of TensorBoard event files generated by TensorFlow / PyTorch (when using tensorboardX)
• API docs: the repo contains example HTTP endpoints and request/response shapes (see doc/ or example clients directory)

Suggested local endpoints (examples):

Note: exact path versions and parameters are documented in the repo; use these as representative examples.

Use Cases

1. Continuous integration guardrails

   • Automatically query the MCP server after each training job to assert that validation loss decreased below a threshold or that accuracy improved. Example:

   curl "http://localhost:8080/mcp/v1/scalars?run=exp1&tag=val/accuracy" \
     | jq '.series | last(.points).value' 
   

   Fail the CI job if the latest value is below required minimum.

2. Custom dashboards and lightweight visualization

   • Build a minimal React/Plotly dashboard that fetches scalar series from the MCP server instead of embedding TensorBoard. Use the /scalars endpoint to retrieve step/value arrays and plot them.

3. Batch comparison of multiple experiments

   • Script a comparison job that lists all runs, gathers a scalar (e.g., loss) for each run and tag, and computes summary statistics (min, final value, epoch of best metric) to rank experiments automatically.

4. Debugging crashed runs

   • Inspect raw event payloads or histogram summaries for a run to discover when metrics diverged or when specific events (e.g., NaNs) first appeared. Use the event streaming endpoint to replay the timeline.

5. Lightweight remote access

   • Expose the MCP server on an internal network or via a reverse proxy to let team members query event data programmatically without VPN or SSH’ing into the training host.

Best Practices

• Keep event files in a consistent directory structure (e.g., by experiment name or timestamp) to make run discovery predictable.
• Use the watch mode for active experiments so the server reflects new events as they are written.
• Use small cache sizes in memory-constrained environments, or front the server with a cache/proxy to handle heavy-read workloads.
• Validate event file compatibility if you use multiple frameworks (TensorFlow vs tensorboardX) — the parser supports common event formats but check for any version-specific limitations in the repo docs.

For full API reference, examples and advanced configuration options, see the GitHub repository: https://github.com/Alir3z4/tb-query.