How do I use tb-query?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tb-query query loss and accuracy from events.out.tfevents.12345" 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.

tb-query

by Alir3z4

Overview Schema Related Servers Score Discussions

Python

Local

tb-query

A CLI tool and MCP (Model Context Protocol) server for querying and analyzing TensorBoard event files without requiring a running TensorBoard server.

Overview

tb-query allows you to directly interact with TensorBoard's events.out.tfevents.* files to extract scalar data, calculate statistics, find correlations, and more. It's particularly useful for:

Programmatic access to training metrics
Automated analysis of training runs
Integration with AI coding agents through MCP
Quick inspection of TensorBoard logs without starting a web server

Related MCP server: trackio-mcp

Features

Query scalar data with step and tag filtering
Find all TensorBoard event files in a directory tree
List available scalar tags with optional filtering
Calculate statistics (min, max, mean, std) for specific tags
Compute correlations between different scalar metrics
CLI interface for command-line usage
MCP server for integration with AI coding assistants

Installation

From PyPI

pip install tb-query

From Source

git clone https://github.com/Alir3z4/tb-query.git
cd tb-query
pip install -e .

Requirements

Python >= 3.11
tensorboard
fastmcp
pandas

CLI Usage

Query Command

Extract scalar data from a TensorBoard event file:

# Query all available tags
tb-query query path/to/events.out.tfevents.12345

# Query specific tags
tb-query query path/to/events.out.tfevents.12345 --tags loss --tags accuracy

# Query with step range filtering
tb-query query path/to/events.out.tfevents.12345 --start_step 100 --end_step 200

# Combine filters
tb-query query path/to/events.out.tfevents.12345 --tags loss --start_step 100 --end_step 200

Output format (JSON):

{
  "loss": [
    {"step": 100, "value": 0.5},
    {"step": 101, "value": 0.48}
  ],
  "accuracy": [
    {"step": 100, "value": 0.85},
    {"step": 101, "value": 0.86}
  ]
}

Tags Command

List all available scalar tags in an event file:

# List all tags
tb-query tags path/to/events.out.tfevents.12345

# Filter tags containing specific strings
tb-query tags path/to/events.out.tfevents.12345 --filter loss
tb-query tags path/to/events.out.tfevents.12345 --filter loss --filter accuracy

Output format (JSON):

{
  "tags": ["train/loss", "train/accuracy", "eval/loss", "eval/accuracy"]
}

Find Command

Locate all TensorBoard event files in a directory:

tb-query find path/to/logs

Output format (JSON):

{
  "event_files": [
    {
      "path": "path/to/logs/run1/events.out.tfevents.12345",
      "created_at": "2025-11-04T10:30:00.123456"
    },
    {
      "path": "path/to/logs/run2/events.out.tfevents.67890",
      "created_at": "2025-11-03T15:20:00.654321"
    }
  ]
}

Files are sorted by creation time (newest first).

Steps Command

Get the step numbers for specific tags:

tb-query steps path/to/events.out.tfevents.12345 --tags loss --tags accuracy

Output format (JSON):

{
  "loss": [0, 10, 20, 30, 40, 50],
  "accuracy": [0, 10, 20, 30, 40, 50]
}

Stats Command

Calculate statistical measures for tag values:

tb-query stats path/to/events.out.tfevents.12345 --tags loss --tags accuracy

Output format (JSON):

{
  "loss": {
    "min": 0.15,
    "max": 2.34,
    "mean": 0.85,
    "std": 0.42,
    "count": 1000
  },
  "accuracy": {
    "min": 0.65,
    "max": 0.98,
    "mean": 0.87,
    "std": 0.08,
    "count": 1000
  }
}

Correlation Command

Calculate Pearson correlations between scalar tags:

# Basic correlation
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy"

# With step range
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy" --start_step 100 --end_step 200

# With interpretation
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy" --display-interpretation true

# Custom rounding
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy" --rounding 6

Output format without interpretation (JSON):

{
  "loss": {
    "accuracy": -0.9234,
    "learning_rate": 0.1234
  }
}

Output format with interpretation (JSON):

{
  "loss": {
    "accuracy": {
      "correlation": -0.9234,
      "interpretation": "Strong negative correlation"
    }
  }
}

MCP Server Usage

tb-query provides an MCP (Model Context Protocol) server that enables AI coding assistants to interact with TensorBoard event files. This allows agents to analyze training runs, extract metrics, and provide insights.

Starting the MCP Server

tb-query-mcp

The server will start and listen for MCP connections from compatible clients.

Environment Variable

You can set the TB_QUERY_EVENTS_PATH environment variable to specify a default directory for event files:

export TB_QUERY_EVENTS_PATH=/path/to/tensorboard/logs
tb-query-mcp

This enables the event_files resource, which automatically lists available event files from the specified directory.

Integration with AI Coding Agents

Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tb-query": {
      "command": "tb-query-mcp",
      "env": {
        "TB_QUERY_EVENTS_PATH": "/path/to/your/tensorboard/logs"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop. The tb-query tools will be available for Claude to use when analyzing your training runs.

Cline (VS Code Extension)

Add to your Cline MCP settings file (.cline/mcp_settings.json in your workspace):

{
  "mcpServers": {
    "tb-query": {
      "command": "tb-query-mcp",
      "env": {
        "TB_QUERY_EVENTS_PATH": "/path/to/your/tensorboard/logs"
      }
    }
  }
}

Zed Editor

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "tb-query": {
      "command": "tb-query-mcp",
      "env": {
        "TB_QUERY_EVENTS_PATH": "/path/to/your/tensorboard/logs"
      }
    }
  }
}

Continue (VS Code Extension)

Add to your Continue config file (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "tb-query",
      "command": "tb-query-mcp",
      "env": {
        "TB_QUERY_EVENTS_PATH": "/path/to/your/tensorboard/logs"
      }
    }
  ]
}

Using with Python Client

You can also integrate tb-query into your own Python scripts using the MCP protocol:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="tb-query-mcp",
    env={"TB_QUERY_EVENTS_PATH": "/path/to/logs"}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Call tools
        result = await session.call_tool("list_tags", {
            "event_file": "/path/to/events.out.tfevents.12345"
        })
        print(result)

Available MCP Tools

When running as an MCP server, tb-query provides the following tools:

query

Query scalar data from a TensorBoard event file.

Parameters:

event_file (string, required): Path to the event file
tags (list[string], optional): List of tags to query (default: all tags)
start_step (integer, optional): Starting step (inclusive)
end_step (integer, optional): Ending step (inclusive)

Get all available scalar tags with optional filtering.

Parameters:

event_file (string, required): Path to the event file
filters (list[string], optional): Filter tags containing these strings

find_events

Find all TensorBoard event files in a directory and subdirectories.

Parameters:

directory (string, required): Directory path to search

tag_steps

Get the step numbers for specified tags.

Parameters:

event_file (string, required): Path to the event file
tags (list[string], required): List of tags

tag_stats

Get statistical measures for specified tags.

Parameters:

event_file (string, required): Path to the event file
tags (list[string], required): List of tags

correlation

Calculate correlations between scalar tags.

Parameters:

event_file (string, required): Path to the event file
tags (list[string], required): Tags to calculate correlations for
start_step (integer, optional): Starting step
end_step (integer, optional): Ending step

Available MCP Resources

event_files

When TB_QUERY_EVENTS_PATH is set, this resource provides a list of all available event files from the configured directory.

URI: resource://event-files

Example Use Cases

Monitoring Training Progress

# Check latest loss values
tb-query query events.out.tfevents.12345 --tags train/loss --start_step 990

# Compare train and validation metrics
tb-query query events.out.tfevents.12345 --tags train/loss --tags val/loss

Analyzing Model Performance

# Get statistics for key metrics
tb-query stats events.out.tfevents.12345 --tags train/accuracy --tags val/accuracy

# Find correlations between metrics
tb-query correlation events.out.tfevents.12345 --tags "loss,learning_rate" --display-interpretation true

AI Agent Integration

When integrated with AI coding assistants through MCP, you can simply ask:

"Analyze the latest training run in my logs directory"
"What's the correlation between loss and learning rate?"
"Show me the statistics for accuracy metrics"
"Compare the last 100 steps of train and validation loss"

The AI agent will automatically use the appropriate tb-query tools to fetch and analyze the data.

Python API

You can also use tb-query directly in your Python code:

from tb_query.core import (
    query_tensorboard,
    get_all_tags,
    find_event_files,
    get_tag_statistics,
    calculate_correlation
)

# Query data
data = query_tensorboard(
    "events.out.tfevents.12345",
    tags=["loss", "accuracy"],
    start_step=100,
    end_step=200
)

# Get tags
tags = get_all_tags("events.out.tfevents.12345", filters=["loss"])

# Get statistics
stats = get_tag_statistics("events.out.tfevents.12345", tags=["loss"])

# Calculate correlation
correlation = calculate_correlation(
    data,
    tags={"loss"},
    rounding=4,
    display_interpretation=True
)

Automated Analysis Scripts

import json
import subprocess

# Find all event files
result = subprocess.run(
    ["tb-query", "find", "logs/"],
    capture_output=True,
    text=True
)
event_files = json.loads(result.stdout)

# Query the most recent file
latest_file = event_files["event_files"][0]["path"]
result = subprocess.run(
    ["tb-query", "query", latest_file, "--tags", "loss"],
    capture_output=True,
    text=True
)
data = json.loads(result.stdout)

# Process the data
print(f"Final loss: {data['loss'][-1]['value']}")

Using the Core Library Directly

The primary purpose of tb-query is to provide a Python library for programmatic access to TensorBoard data. All functionality is available through the tb_query.core module:

from tb_query.core import (
    query_tensorboard,
    get_all_tags,
    find_event_files,
    get_tag_steps,
    get_tag_statistics,
    calculate_correlation,
    ValidationError
)

# Find all event files in a directory
try:
    result = find_event_files("logs/")
    event_files = result["event_files"]
    print(f"Found {len(event_files)} event files")
    
    # Use the most recent file
    latest_file = event_files[0]["path"]
    print(f"Analyzing: {latest_file}")
    
except ValidationError as e:
    print(f"Error: {e.message}")

# Get all available tags
try:
    tags_result = get_all_tags(latest_file)
    all_tags = tags_result["tags"]
    print(f"Available tags: {all_tags}")
    
    # Filter tags containing "loss"
    loss_tags = get_all_tags(latest_file, filters=["loss"])
    print(f"Loss-related tags: {loss_tags['tags']}")
    
except ValidationError as e:
    print(f"Error: {e.message}")

# Query specific tags with step filtering
try:
    data = query_tensorboard(
        event_file=latest_file,
        tags=["train/loss", "val/loss"],
        start_step=100,
        end_step=500
    )
    
    for tag, values in data.items():
        print(f"\n{tag}:")
        print(f"  First value: step={values[0]['step']}, value={values[0]['value']}")
        print(f"  Last value: step={values[-1]['step']}, value={values[-1]['value']}")
        print(f"  Total points: {len(values)}")
        
except ValidationError as e:
    print(f"Error: {e.message}")

# Get statistics for tags
try:
    stats = get_tag_statistics(latest_file, tags=["train/loss", "train/accuracy"])
    
    for tag, stat in stats.items():
        if "error" in stat:
            print(f"{tag}: {stat['error']}")
        else:
            print(f"\n{tag} statistics:")
            print(f"  Min: {stat['min']:.4f}")
            print(f"  Max: {stat['max']:.4f}")
            print(f"  Mean: {stat['mean']:.4f}")
            print(f"  Std: {stat['std']:.4f}")
            print(f"  Count: {stat['count']}")
            
except ValidationError as e:
    print(f"Error: {e.message}")

# Get available steps for specific tags
try:
    steps = get_tag_steps(latest_file, tags=["train/loss", "val/loss"])
    
    for tag, step_list in steps.items():
        print(f"{tag}: {len(step_list)} steps")
        print(f"  Range: {step_list[0]} to {step_list[-1]}")
        
except ValidationError as e:
    print(f"Error: {e.message}")

# Calculate correlations
try:
    # First query the data
    data = query_tensorboard(
        event_file=latest_file,
        tags=None,  # Get all tags
        start_step=0,
        end_step=1000
    )
    
    # Calculate correlation for specific tags
    correlation = calculate_correlation(
        data=data,
        tags={"train/loss"},  # Primary tag(s) to correlate against others
        rounding=4,
        display_interpretation=False
    )
    
    print("\nCorrelations with train/loss:")
    for other_tag, corr_value in correlation["train/loss"].items():
        print(f"  {other_tag}: {corr_value}")
    
    # With interpretation
    correlation_interpreted = calculate_correlation(
        data=data,
        tags={"train/loss"},
        rounding=4,
        display_interpretation=True
    )
    
    print("\nCorrelations with interpretation:")
    for other_tag, corr_data in correlation_interpreted["train/loss"].items():
        print(f"  {other_tag}:")
        print(f"    Correlation: {corr_data['correlation']}")
        print(f"    Interpretation: {corr_data['interpretation']}")
        
except ValidationError as e:
    print(f"Error: {e.message}")

# Complete analysis workflow
def analyze_training_run(event_file_path: str):
    """Complete analysis of a training run."""
    try:
        # Get all tags
        tags_result = get_all_tags(event_file_path)
        all_tags = tags_result["tags"]
        
        # Get statistics for all tags
        stats = get_tag_statistics(event_file_path, tags=all_tags)
        
        # Query recent data (last 100 steps)
        data = query_tensorboard(event_file_path, tags=all_tags)
        
        # Get the maximum step across all tags
        max_step = 0
        for tag_data in data.values():
            if tag_data:
                max_step = max(max_step, tag_data[-1]["step"])
        
        # Query only recent data
        recent_data = query_tensorboard(
            event_file_path,
            tags=all_tags,
            start_step=max(0, max_step - 100),
            end_step=max_step
        )
        
        # Calculate correlations
        correlation = calculate_correlation(
            data=data,
            tags=set(all_tags[:5]),  # Limit to first 5 tags to avoid huge output
            rounding=4,
            display_interpretation=True
        )
        
        return {
            "tags": all_tags,
            "statistics": stats,
            "recent_data": recent_data,
            "correlations": correlation,
            "max_step": max_step
        }
        
    except ValidationError as e:
        return {"error": e.message}

# Use the analysis function
result = analyze_training_run("events.out.tfevents.12345")
if "error" in result:
    print(f"Analysis failed: {result['error']}")
else:
    print(f"Analysis complete: {len(result['tags'])} tags analyzed")
    print(f"Training ran for {result['max_step']} steps")

All functions in tb_query.core raise ValidationError exceptions for file access or parsing errors, so wrapping calls in try-except blocks is recommended for robust error handling.

Error Handling

tb-query provides clear error messages for common issues:

File not found: Raised when the specified event file doesn't exist
Failed to load event file: Raised when the file is corrupted or invalid
Directory not found: Raised when the specified directory doesn't exist
Tag not found: Returned in statistics when a requested tag doesn't exist
No values found: Returned when a tag exists but has no data points

Development

Setup Development Environment

git clone https://github.com/Alir3z4/tb-query.git
cd tb-query
make install

Run Tests

Currently, the code base doesn't include tests and I plan to add them later.

Running the tests

make test

Running the tests with coverage

# Run tests with coverage
make coverage
coverage report

Code Quality

make lint

Pre Commit

There is a makefile task that runs the formatting and type checking. To be used before commiting the code.

make precommit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the GPL-3.0-or-later License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Available Tools

6 tools

correlationB

Calculate the correlation between scalar tags in a TensorBoard event file

It will provide correlation for the given tag(s) with other tags in the tensorboard data.

ParametersJSON Schema

Name	Required	Description
`event_file`	Yes	Path of the tensorboard event file.
`tags`	Yes	List of tags to show correlation for with other tags.
`start_step`	No	Query the scalar data starting with this step.
`end_step`	No	Query the scalar data until this step.

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits but only states 'calculate correlation', implying a read-only computation. It does not mention performance implications, error conditions (e.g., missing tags), correlation method (e.g., Pearson), or any side effects, leaving significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and front-loaded with the core purpose. The second sentence is slightly redundant but not wasteful. Overall, it is concise and contains no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is reasonably complete for a tool with a provided output schema (which can describe return values). However, it lacks specificity on the correlation method used and whether correlations are computed pairwise between all tags. This ambiguity prevents a higher score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters' meaning is already defined in the schema. The description adds minimal extra value, only clarifying that tags are correlated 'with other tags'. This meets the baseline of 3 without adding significant new semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool calculates correlation between scalar tags in a TensorBoard event file, specifying the action (calculate) and resource (scalar tags). This verb+resource combination distinguishes it from siblings like query or tag_stats, which likely fetch raw data rather than compute relationships.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. It describes what the tool does but lacks any when-to-use, when-not-to-use, or alternative recommendations, leaving the agent to infer usage from purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_eventsA

Find all TensorBoard event files in the specified directory and its subdirectories.

Use this endpoint when you don't know the available events or user has not given you any event file name to analyze.

ParametersJSON Schema

Name	Required	Description	Default
`directory`	Yes	Path of the directory to find all the tensorboard events file in.

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes	List event found event files.

TDQS

A4.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only says 'find all... in directory and subdirectories' without disclosing error handling, performance, or return format. More behavioral context is needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundancy. First sentence states purpose, second gives usage guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter and an output schema, the description is mostly complete. However, missing behavioral transparency (e.g., directory validity) reduces contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter description. Description adds value by specifying 'and its subdirectories', which is not in the schema, clarifying recursive search.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'find' and the resource 'TensorBoard event files' in directories recursively. It distinguishes from sibling tools that focus on tags, queries, and stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'when you don't know the available events or user has not given you any event file name to analyze.' This provides clear context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tagsA

Get all available scalar tags from a TensorBoard event file with optional filtering.

To search/filter the returning tags, you can pass a list of string to the filters parameter, which will only return the tags that contain those filter strings.

ParametersJSON Schema

Name	Required	Description	Default
`event_file`	Yes	Path of the tensorboard event file.
`filters`	No	List of filters to match the tag names. If a filter is given, any tag name that includes the given characters in the filter will be returned.

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes	List of tags available in the Tensorboard event file.

TDQS

A4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It only mentions functionality and filtering, but it omits read-only status, error conditions (e.g., invalid file), performance implications, or what happens when no tags exist. This leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the core purpose. Every sentence is necessary and no redundant information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a simple interface (2 parameters, no enums, no nested objects) and an output schema exists, the description covers the main use case and filtering. However, it could mention that the tool is read-only or safe to call, but since the output schema is present, the lack of return format details is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds clarification on how the filters parameter works, specifying that tags containing filter strings are returned. This goes beyond the schema description by explaining the matching behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists scalar tags from a TensorBoard event file with optional filtering. The verb 'get' and resource 'scalar tags' are specific, and sibling tools like tag_stats or tag_steps are distinct in function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the filters parameter to narrow results, providing clear usage guidance. However, it does not explicitly state when not to use the tool or mention alternatives like the 'query' tool for complex searches, so it's slightly incomplete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryA

Query scalar data from a TensorBoard event file.

This will return all the data inside the Tensorboard event files. The result for a long training is very big and can consume all your context limit if not properly filtered by tags and start_step and end_step.

To know the available event files you can use find_events tool to get all the available event files.
To know the available tags of a Tensorboard file, you may use list_tags which gives you all the available scalar tags in the event file.
To know all the available training steps for each tag, you can use tag_steps tool.
Use start_step and end_step to ask for a range of data.
Try to use tags explicitly, otherwise the output can be huge.

ParametersJSON Schema

Name	Required	Description
`event_file`	Yes	Path of the tensorboard event file.
`tags`	No	List of tags to show. If not provided, all the tags will be queried.
`start_step`	No	Query the scalar data starting with this step.
`end_step`	No	Query the scalar data until this step.

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description fully carries the burden. It clearly states that the result can be very large and consume context limit if not filtered, and that it returns all data if no filters are applied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with bullet points and clear warnings. Slightly long but every sentence adds value, and the format aids readability for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a query tool with an output schema. Warns about large data, explains filtering, and references sibling tools. Adequately prepares the agent for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters are documented in the schema (100% coverage). The description adds value by explaining the impact of not filtering (tags, steps) and how to use start_step/end_step for ranges, but the schema already covers basics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly states 'Query scalar data from a TensorBoard event file', clearly identifying the action and resource. It differentiates from siblings like list_tags and tag_steps which deal with metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool (to get scalar data) and when to avoid (large outputs). Recommends using tags and step filters, and references sibling tools (find_events, list_tags, tag_steps) for prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tag_statsA

Get statistical measures (min, max, mean, std) for each specified tag's values.

ParametersJSON Schema

Name	Required	Description	Default
`event_file`	Yes	Path of the tensorboard event file.
`tags`	Yes	List of tags to show the stats for.

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It clearly states the tool computes min, max, mean, std, which implies a read-only operation. However, it does not explicitly confirm no side effects or mention data handling assumptions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 14 words, front-loaded with the key action and output. No wasted content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is straightforward, has an output schema (so return value explanation is not needed), and has 100% schema coverage, the description is complete enough for an AI agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, so the baseline is 3. The description does not add additional semantic detail beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('Get'), the resource ('statistical measures'), and the scope ('for each specified tag's values'). It distinguishes from siblings like 'correlation' or 'query' by focusing on statistical measures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives such as 'query' or 'tag_steps'. Usage is implied from the description, but no when-not or alternative tool names are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tag_stepsA

Get the steps for each specified tag from a TensorBoard event file.

Pass tags to get return steps for only specified tags, otherwise the output can be quite large.

ParametersJSON Schema

Name	Required	Description	Default
`event_file`	Yes	Path of the tensorboard event file.
`tags`	Yes	List of tags to show the steps for.

Output Schema

ParametersJSON Schema

Name	Required	Description
`results`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description notes that output can be large without tags, but does not disclose other behavioral traits like performance or side effects. With no annotations, it carries a moderate burden but still lacks detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, no extraneous words. Every sentence contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description is sufficient for understanding purpose and usage. Could mention prerequisites (e.g., event file existence) but overall complete for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema already describes both parameters with 100% coverage. The description adds value by explaining why the 'tags' parameter is important (avoid large output), going beyond schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get the steps') and resource ('each specified tag from a TensorBoard event file'). It distinguishes from sibling tools like list_tags (which lists tags) and tag_stats (which gives statistics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on using the 'tags' parameter to avoid large output, implying when it's beneficial to specify tags. Does not explicitly discuss alternatives but clearly differentiates from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.1.0May 27, 2026
- First observedcorrelation
- First observedfind_events
- First observedlist_tags
- First observedquery
- First observedtag_stats
- First observedtag_steps

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool has a distinct purpose: finding files, listing tags, querying data, getting steps, statistics, and correlations. No two tools overlap in functionality.

Naming Consistency3/5

Tools use a mix of verb_noun (find_events, list_tags) and noun_noun (tag_steps, tag_stats) patterns, plus single-word verbs (query) and nouns (correlation). The pattern is inconsistent but still readable.

Tool Count5/5

With 6 tools, the server covers all necessary operations for querying TensorBoard scalar data without being excessive or minimal.

Completeness4/5

The tool set provides a complete workflow: discover files, list tags, get steps, query data, compute statistics, and correlate. Minor gaps like comparing runs are missing but not critical.

Maintenance

ActivityInactive

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
Backtest360 A
com.backtest360
MCP server exposing the Backtest360 engine API as tools for AI agents.
Finance Research & Data
202
crypto-defi-mcpOAuth
com.thenextgennexus
MCP server giving AI agents one-connection access to crypto & DeFi data: DeFi protocol TVL, stableco
Cryptocurrency Finance Blockchain
2
mcp AOAuth
io.scorecard
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
RAG Systems Monitoring Testing & QA Tools
3

Related MCP Servers

Zaturn
Databases Data Platforms
kdqed
A
license
A
quality
C
maintenance
An open-source MCP server that connects to various data sources (SQL databases, CSV, Parquet files), allowing AI models to execute SQL queries and generate data visualizations for analytics and business intelligence.
Updated 10 months ago (2025-11-12 06:17 UTC)
12
75
MIT
trackio-mcp
RAG Systems Monitoring Developer Tools
fcakyon
A
license
Not graded
quality
C
maintenance
An MCP server that enables AI agents to observe and interact with trackio experiment tracking, providing tools for managing ML experiments through natural language.
Updated a year ago (2025-08-03 13:39 UTC)
3
MIT
otel-mcp
Observability Monitoring
moondef
A
license
A
quality
D
maintenance
MCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.
Updated 8 months ago (2025-12-29 19:56 UTC)
5
16
2
MIT
MCP TensorBoard
AI & Machine Learning Data Visualization Research & Data
1Kraks
A
license
Not graded
quality
C
maintenance
Exposes TensorBoard experiment data through a standardized MCP API, enabling AI coding agents to query and analyze scalars, tensors, histograms, distributions, and images from ML experiment logs.
Updated 12 days ago (2026-08-25 19:58 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Alir3z4/tb-query'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

tb-query

Overview

Features

Installation

From PyPI

From Source

Requirements

CLI Usage

Query Command

Tags Command

Find Command

Steps Command

Stats Command

Correlation Command

MCP Server Usage

Starting the MCP Server

Environment Variable

Integration with AI Coding Agents

Claude Desktop

Cline (VS Code Extension)

Zed Editor

Continue (VS Code Extension)

Using with Python Client

Available MCP Tools

query

list_tags

find_events

tag_steps

tag_stats

correlation

Available MCP Resources

event_files

Example Use Cases

Monitoring Training Progress

Analyzing Model Performance

AI Agent Integration

Python API

Automated Analysis Scripts

Using the Core Library Directly

Error Handling

Development

Setup Development Environment

Run Tests

Running the tests

Running the tests with coverage

Code Quality

Pre Commit

Contributing

License

Links

Support

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API