trackio-mcp 0.2.0
MCP (Model Context Protocol) server support for trackio experiment tracking
Requires Python: >=3.10
Keywords: AI agents, MCP, Model Context Protocol, experiment tracking, gradio, machine learning, trackio

# trackio-mcp

[![PyPI version](https://badge.fury.io/py/trackio-mcp.svg)](https://badge.fury.io/py/trackio-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/fcakyon/trackio-mcp/workflows/CI%20with%20uv/badge.svg)](https://github.com/fcakyon/trackio-mcp/actions)

**MCP (Model Context Protocol) server support for trackio experiment tracking**

This package enables AI agents to observe and interact with [trackio](https://github.com/gradio-app/trackio) experiments through the Model Context Protocol (MCP). Simply import `trackio_mcp` before `trackio` to automatically enable MCP server functionality.

## Features

- **Zero-code integration**: Just import `trackio_mcp` before `trackio` 
- **Automatic MCP server**: Enables MCP server on all trackio deployments (local & Spaces)
- **Rich tool set**: Exposes trackio functionality as MCP tools for AI agents
- **Spaces compatible**: Works seamlessly with Hugging Face Spaces deployments
- **Drop-in replacement**: No changes needed to existing trackio code

## Installation

```bash
pip install trackio-mcp
```

Or with development dependencies:

```bash
pip install trackio-mcp[dev]
```

## Quick Start

### Basic Usage

Simply import `trackio_mcp` before importing `trackio`:

```python
import trackio_mcp  # This enables MCP server functionality
import trackio as wandb

# Your existing trackio code works unchanged
wandb.init(project="my-experiment")
wandb.log({"loss": 0.1, "accuracy": 0.95})
wandb.finish()
```

The MCP server will be automatically available at:
- **Local**: `http://localhost:7860/gradio_api/mcp/sse` 
- **Spaces**: `https://your-space.hf.space/gradio_api/mcp/sse`

### Deploy to Hugging Face Spaces with MCP

```python
import trackio_mcp
import trackio as wandb

# Deploy to Spaces with MCP enabled automatically
wandb.init(
    project="my-experiment", 
    space_id="username/my-trackio-space"
)

wandb.log({"loss": 0.1})
wandb.finish()
```

### Standalone MCP Server

Launch a dedicated MCP server for trackio tools:

```python
from trackio_mcp.tools import launch_trackio_mcp_server

# Launch standalone MCP server on port 7861
launch_trackio_mcp_server(port=7861, share=False)
```

## Available MCP Tools

Once connected, AI agents can use these trackio tools:

### Core Tools (via Gradio API)
- **log**: Log metrics to a trackio run
- **upload_db_to_space**: Upload local database to a Space

### Extended Tools (via trackio-mcp)
- **get_projects**: List all trackio projects
- **get_runs**: Get runs for a specific project  
- **filter_runs**: Filter runs by name pattern
- **get_run_metrics**: Get metrics data for a specific run
- **get_available_metrics**: Get all available metric names for a project
- **load_run_data**: Load and process run data with optional smoothing
- **get_project_summary**: Get comprehensive project statistics

### Example Agent Interaction

```
Human: "Show me the latest results from my 'image-classification' project"

Agent: I'll check your trackio projects and get the latest results.

[Tool: get_projects] → finds "image-classification" project
[Tool: get_runs] → gets runs for "image-classification" 
[Tool: get_run_metrics] → gets metrics for latest run
[Tool: get_available_metrics] → gets metric names

Agent: Your latest image-classification run achieved 94.2% accuracy with a final loss of 0.18. The model trained for 50 epochs with best validation accuracy of 94.7% at epoch 45.
```

## MCP Client Configuration

<details>
<summary><b>Claude Desktop</b></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:

**Public Spaces:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more info.

**Public Spaces:**
```sh
claude mcp add --transport sse trackio https://your-space.hf.space/gradio_api/mcp/sse
```

**Private Spaces/Datasets:**
```sh
claude mcp add --transport sse --header "Authorization: Bearer YOUR_HF_TOKEN" trackio https://your-private-space.hf.space/gradio_api/mcp/sse
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

Add to your Cursor `~/.cursor/mcp.json` file or create `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

**Public Spaces:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

Add to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.

**Public Spaces:**
```json
{
  "mcpServers": {
    "trackio": {
      "serverUrl": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcpServers": {
    "trackio": {
      "serverUrl": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "serverUrl": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

Add to `.vscode/mcp.json`. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

**Public Spaces:**
```json
{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http",
        "url": "https://your-space.hf.space/gradio_api/mcp/sse"
      }
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http", 
        "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
        "headers": {
          "Authorization": "Bearer YOUR_HF_TOKEN"
        }
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcp": {
    "servers": {
      "trackio": {
        "type": "http",
        "url": "http://localhost:7860/gradio_api/mcp/sse"
      }
    }
  }
}
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

Add to `mcp.json` in your project directory. See [Gemini CLI Configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md) for details.

**Public Spaces:**
```json
{
  "mcpServers": {
    "trackio": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-space.hf.space/gradio_api/mcp/sse"]
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcpServers": {
    "trackio": {
      "command": "npx", 
      "args": ["mcp-remote", "https://your-private-space.hf.space/gradio_api/mcp/sse"],
      "env": {
        "HF_TOKEN": "YOUR_HF_TOKEN"
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:7860/gradio_api/mcp/sse"]
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

Create `.cursor/mcp.json` (or equivalent for your IDE):

**Public Spaces:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-space.hf.space/gradio_api/mcp/sse"
    }
  }
}
```

**Private Spaces/Datasets:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_HF_TOKEN"
      }
    }
  }
}
```

**Local Development:**
```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

</details>

## Configuration

### Environment Variables

- `TRACKIO_DISABLE_MCP`: Set to `"true"` to disable MCP functionality (default: MCP enabled)

### Programmatic Control

```python
import os
os.environ["TRACKIO_DISABLE_MCP"] = "true"  # Disable MCP
import trackio_mcp  # MCP won't be enabled
import trackio
```

## How It Works

`trackio-mcp` uses monkey-patching to automatically:

1. **Enable MCP server**: Sets `mcp_server=True` on all Gradio launches
2. **Enable API**: Sets `show_api=True` to expose Gradio API endpoints  
3. **Add tools**: Registers additional trackio-specific MCP tools
4. **Preserve compatibility**: No changes needed to existing trackio code

The package patches:
- `gradio.Blocks.launch()` - Core Gradio launch method
- `trackio.ui.demo.launch()` - Trackio dashboard launches
- Adds new MCP endpoints at `/gradio_api/mcp/sse`

## Deployment Examples

### Local Development

```python
import trackio_mcp
import trackio

# Start local tracking with MCP enabled
trackio.show()  # Dashboard + MCP server at http://localhost:7860
```

### Public Spaces Deployment

```python
import trackio_mcp
import trackio as wandb

# Deploy to public Spaces with MCP support
wandb.init(
    project="public-model",
    space_id="username/model-tracking"
)

wandb.log({"epoch": 1, "loss": 0.5})
wandb.finish()
```

### Private Spaces/Datasets Deployment

```python
import trackio_mcp
import trackio as wandb

# Deploy to private Spaces with private dataset
wandb.init(
    project="private-model",
    space_id="organization/private-model-tracking",  # Private space
    dataset_id="organization/private-model-metrics"  # Private dataset
)

wandb.log({"epoch": 1, "loss": 0.5})
wandb.finish()
```

## CLI Interface

```bash
# Launch standalone MCP server
trackio-mcp server --port 7861

# Check status and configuration
trackio-mcp status

# Test MCP server functionality
trackio-mcp test --url http://localhost:7860
```

## Security Considerations

- **Private Spaces**: Use HF tokens for authentication with private spaces/datasets
- **Access Control**: MCP server inherits trackio's access controls
- **Network Security**: Consider firewall rules for production deployments
- **Token Management**: Store HF tokens securely, use environment variables

## Troubleshooting

### MCP Server Not Available

```python
import trackio_mcp
import trackio

# Check if MCP was disabled
import os
print("MCP Disabled:", os.getenv("TRACKIO_DISABLE_MCP"))

# Manual verification
trackio.show()  # Look for MCP server URL in output
```

### Connection Issues

1. **Check URL**: Ensure correct `/gradio_api/mcp/sse` endpoint
2. **Authentication**: Add Bearer token for private Spaces/datasets
3. **Network**: Verify firewall/proxy settings
4. **Dependencies**: Ensure `gradio[mcp]` is installed

### Tool Discovery Issues

```python
# Test tools manually
from trackio_mcp.tools import register_trackio_tools

tools = register_trackio_tools()
tools.launch(mcp_server=True)  # Test tools interface
```

## Contributing

1. Fork the repository
2. Install development dependencies: `pip install -e .[dev]`
3. Make your changes
4. Run tests: `pytest`
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file.

## Acknowledgments

- [trackio](https://github.com/gradio-app/trackio) - The excellent experiment tracking library
- [Gradio](https://gradio.app) - For built-in MCP server support
- [Model Context Protocol](https://modelcontextprotocol.io) - For the standardized AI tool protocol

---

**Made with care for the AI research community**