MCP TensorBoard

A Model Context Protocol (MCP) server that exposes TensorBoard data through a standardized API. Built with FastMCP, this server enables AI coding agents to query and analyze TensorBoard experiment data programmatically.

Features

• Pure Python implementation - No subprocess or external binaries required
• Multiple transports - stdio, Streamable HTTP, and SSE
• Full TensorBoard support - Scalars, tensors, histograms, distributions, and images
• Structured output - Pydantic models for type-safe, validated responses
• AI-optimized - Compact data formats ideal for LLM consumption

Quickstart

Run directly from GitHub (no installation)

uvx --from git+https://github.com/1Kraks/mcp-tensorboard mcp-tensorboard --logdir /path/to/logs

Install with uv (recommended)

# Clone the repository
git clone https://github.com/1Kraks/mcp-tensorboard
cd mcp-tensorboard

# Create virtual environment and install
uv venv
source .venv/bin/activate  # macOS/Linux
uv sync

# Run the server
uv run mcp-tensorboard --logdir /path/to/logs

Install with pip

pip install -e .
mcp-tensorboard --logdir /path/to/logs

Usage

Command Line Options

mcp-tensorboard --logdir <path> [--transport stdio|http|sse] [--port PORT] [--host HOST] [--debug]

Option	Default	Description
--logdir	(required)	Path to TensorBoard logs directory
--transport	stdio	Transport protocol
--port	8000	Port for HTTP/SSE transport
--host	0.0.0.0	Host for HTTP/SSE transport
--debug	off	Enable debug logging

Environment Variables

• TENSORBOARD_LOGDIR - Default log directory (alternative to --logdir)
• TENSORBOARD_LOGS - Alternative log directory variable

Available Tools

Run Management

Tool	Description
tensorboard_list_runs	List all runs in the log directory

Scalars

Tool	Description
tensorboard_list_scalar_tags	List scalar tags for a run
tensorboard_get_scalar_series	Get time series for a scalar
tensorboard_get_scalar_series_batch	Get multiple scalars in one call
tensorboard_get_scalar_last	Get the most recent scalar value

Tensors

Tool	Description
tensorboard_list_tensor_tags	List tensor tags for a run
tensorboard_get_tensor_series	Get time series for scalar tensors

Histograms & Distributions

Tool	Description
tensorboard_list_histogram_tags	List histogram tags
tensorboard_get_histogram_series	Get raw histogram data
tensorboard_list_distribution_tags	List distribution tags (alias)
tensorboard_get_distribution_series	Get compressed distributions (recommended)

Images

Tool	Description
tensorboard_list_image_tags	List image tags
tensorboard_get_image_series	Get image references (blob keys)
tensorboard_get_image	Fetch image by blob key (returns base64)

RL Reward Analysis (Stage 4)

Tool	Description
reward_list_experiments	List all reward experiments with metadata
reward_get_stats	Get summary statistics for a reward experiment
reward_compare	Compare multiple reward functions side-by-side
reward_get_trajectories	Get training trajectories for analysis
reward_summary_report	Generate comprehensive analysis report

Convergence Analysis

Tool	Description
reward_rank_by_convergence	Rank rewards by convergence speed (steps to threshold GC)
reward_get_convergence_summary	Get summary statistics for convergence analysis

Convergence Metrics:

• steps_to_threshold — First checkpoint where goal_completion >= threshold
• gc_at_threshold — GC value at threshold step (tie-breaker for same-step convergence)
• converged — Whether threshold was reached

Usage Example:

{
  "method": "tools/call",
  "params": {
    "name": "reward_rank_by_convergence",
    "arguments": {
      "reward_ids": ["reward_0001", "reward_0002", "reward_0003"],
      "threshold": 0.95
    }
  }
}

Ranking Logic:

1. Converged rewards ranked before non-converged
2. Among converged: lower steps = better (faster learning)
3. Tie-breaker: higher GC at threshold = better

Integration with Coding Agents

Claude Code

Option 1: Run from git (no install)

claude mcp add --transport http tensorboard-http \
  uvx --from git+https://github.com/1Kraks/mcp-tensorboard mcp-tensorboard --logdir /path/to/logs --transport http

Option 2: Local installation

# Install globally or in a shared venv
pip install -e /path/to/mcp-tensorboard

# Add to Claude Code
claude mcp add tensorboard mcp-tensorboard --logdir /path/to/logs

Option 3: Via Claude Code settings.json

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "tensorboard": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1Kraks/mcp-tensorboard",
        "mcp-tensorboard",
        "--logdir",
        "/path/to/logs"
      ]
    }
  }
}

GitHub Copilot / VS Code

Add to VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "tensorboard": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1Kraks/mcp-tensorboard",
        "mcp-tensorboard",
        "--logdir",
        "/path/to/logs"
      ]
    }
  }
}

Cline (VS Code Extension)

Add to Cline's MCP settings:

{
  "mcpServers": {
    "tensorboard": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1Kraks/mcp-tensorboard",
        "mcp-tensorboard",
        "--logdir",
        "/path/to/logs"
      ]
    }
  }
}

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "tensorboard": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1Kraks/mcp-tensorboard",
        "mcp-tensorboard",
        "--logdir",
        "/path/to/logs"
      ]
    }
  }
}

Generic MCP Client (Streamable HTTP)

For HTTP transport, run the server:

mcp-tensorboard --logdir /path/to/logs --transport http --port 8000

Connect to http://localhost:8000/mcp from any MCP-compatible client.

Example Usage

List all runs

{
  "method": "tools/call",
  "params": {
    "name": "tensorboard_list_runs",
    "arguments": {}
  }
}

Get scalar training loss over time

{
  "method": "tools/call",
  "params": {
    "name": "tensorboard_get_scalar_series",
    "arguments": {
      "run": ".",
      "tag": "loss",
      "max_points": 500
    }
  }
}

Compare multiple metrics

{
  "method": "tools/call",
  "params": {
    "name": "tensorboard_get_scalar_series_batch",
    "arguments": {
      "run": "experiment_1",
      "tags": ["loss", "accuracy", "val_loss", "val_accuracy"],
      "max_points": 200
    }
  }
}

Get compressed distribution (AI-friendly)

{
  "method": "tools/call",
  "params": {
    "name": "tensorboard_get_distribution_series",
    "arguments": {
      "run": ".",
      "tag": "weights",
      "max_points": 50
    }
  }
}

Development

Setup

# Clone and set up environment
git clone https://github.com/1Kraks/mcp-tensorboard
cd mcp-tensorboard
uv venv
source .venv/bin/activate
uv sync --all-extras

Run tests

pytest

Run with debug logging

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

Code style

# Format code
ruff format .

# Lint
ruff check .

Project Structure

mcp-tensorboard/
├── pyproject.toml              # Project configuration
├── README.md                   # This file
├── src/mcp_tensorboard/
│   ├── __init__.py             # Package init
│   ├── __main__.py             # python -m entry point
│   ├── server.py               # FastMCP server & tools
│   ├── data_reader.py          # Pure Python event file reader
│   └── types.py                # Pydantic response models
└── tests/
    └── test_server.py          # Unit tests

Troubleshooting

No runs found

• Ensure --logdir points to the directory containing TensorBoard event files
• Event files are typically named events.out.tfevents.*

Import errors

• Run uv sync or pip install -e . to install dependencies

HTTP transport not connecting

• Verify the server is running: curl http://localhost:8000/mcp
• Check firewall settings for the specified port

Images not displaying

• Image support requires Pillow: pip install pillow
• Some TensorBoard image formats may not be supported

License

MIT License - See LICENSE file for details.