https://github.com/fcakyon/trackio-mcp
MCP (Model Context Protocol) server support for trackio experiment tracking
https://github.com/fcakyon/trackio-mcp
Last synced: 12 months ago
JSON representation
MCP (Model Context Protocol) server support for trackio experiment tracking
- Host: GitHub
- URL: https://github.com/fcakyon/trackio-mcp
- Owner: fcakyon
- License: mit
- Created: 2025-08-03T10:58:09.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-03T13:39:43.000Z (about 1 year ago)
- Last Synced: 2025-08-10T13:39:45.422Z (12 months ago)
- Language: Python
- Size: 59.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# trackio-mcp
[](https://badge.fury.io/py/trackio-mcp)
[](https://opensource.org/licenses/MIT)
[](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
Claude Desktop
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"
}
}
}
```
Claude Code
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"
}
}
}
```
Cursor
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"
}
}
}
```
Windsurf
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"
}
}
}
```
VS Code
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"
}
}
}
}
```
Gemini CLI
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"]
}
}
}
```
Cline
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"
}
}
}
```
## 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**