trackio-mcp

# 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 <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**