{"id":30135725,"url":"https://github.com/fcakyon/trackio-mcp","last_synced_at":"2025-08-10T22:52:28.705Z","repository":{"id":307978667,"uuid":"1031254043","full_name":"fcakyon/trackio-mcp","owner":"fcakyon","description":"MCP (Model Context Protocol) server support for trackio experiment tracking","archived":false,"fork":false,"pushed_at":"2025-08-03T13:39:43.000Z","size":61,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T13:39:45.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fcakyon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-03T10:58:09.000Z","updated_at":"2025-08-06T22:44:13.000Z","dependencies_parsed_at":"2025-08-03T12:34:29.805Z","dependency_job_id":"396818d4-26d4-4085-aa6d-7d3d7bf53bed","html_url":"https://github.com/fcakyon/trackio-mcp","commit_stats":null,"previous_names":["fcakyon/trackio-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fcakyon/trackio-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Ftrackio-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Ftrackio-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Ftrackio-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Ftrackio-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fcakyon","download_url":"https://codeload.github.com/fcakyon/trackio-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fcakyon%2Ftrackio-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269735572,"owners_count":24466898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-10T22:52:19.780Z","updated_at":"2025-08-10T22:52:28.669Z","avatar_url":"https://github.com/fcakyon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trackio-mcp\n\n[![PyPI version](https://badge.fury.io/py/trackio-mcp.svg)](https://badge.fury.io/py/trackio-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/fcakyon/trackio-mcp/workflows/CI%20with%20uv/badge.svg)](https://github.com/fcakyon/trackio-mcp/actions)\n\n**MCP (Model Context Protocol) server support for trackio experiment tracking**\n\nThis 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.\n\n## Features\n\n- **Zero-code integration**: Just import `trackio_mcp` before `trackio` \n- **Automatic MCP server**: Enables MCP server on all trackio deployments (local \u0026 Spaces)\n- **Rich tool set**: Exposes trackio functionality as MCP tools for AI agents\n- **Spaces compatible**: Works seamlessly with Hugging Face Spaces deployments\n- **Drop-in replacement**: No changes needed to existing trackio code\n\n## Installation\n\n```bash\npip install trackio-mcp\n```\n\nOr with development dependencies:\n\n```bash\npip install trackio-mcp[dev]\n```\n\n## Quick Start\n\n### Basic Usage\n\nSimply import `trackio_mcp` before importing `trackio`:\n\n```python\nimport trackio_mcp  # This enables MCP server functionality\nimport trackio as wandb\n\n# Your existing trackio code works unchanged\nwandb.init(project=\"my-experiment\")\nwandb.log({\"loss\": 0.1, \"accuracy\": 0.95})\nwandb.finish()\n```\n\nThe MCP server will be automatically available at:\n- **Local**: `http://localhost:7860/gradio_api/mcp/sse` \n- **Spaces**: `https://your-space.hf.space/gradio_api/mcp/sse`\n\n### Deploy to Hugging Face Spaces with MCP\n\n```python\nimport trackio_mcp\nimport trackio as wandb\n\n# Deploy to Spaces with MCP enabled automatically\nwandb.init(\n    project=\"my-experiment\", \n    space_id=\"username/my-trackio-space\"\n)\n\nwandb.log({\"loss\": 0.1})\nwandb.finish()\n```\n\n### Standalone MCP Server\n\nLaunch a dedicated MCP server for trackio tools:\n\n```python\nfrom trackio_mcp.tools import launch_trackio_mcp_server\n\n# Launch standalone MCP server on port 7861\nlaunch_trackio_mcp_server(port=7861, share=False)\n```\n\n## Available MCP Tools\n\nOnce connected, AI agents can use these trackio tools:\n\n### Core Tools (via Gradio API)\n- **log**: Log metrics to a trackio run\n- **upload_db_to_space**: Upload local database to a Space\n\n### Extended Tools (via trackio-mcp)\n- **get_projects**: List all trackio projects\n- **get_runs**: Get runs for a specific project  \n- **filter_runs**: Filter runs by name pattern\n- **get_run_metrics**: Get metrics data for a specific run\n- **get_available_metrics**: Get all available metric names for a project\n- **load_run_data**: Load and process run data with optional smoothing\n- **get_project_summary**: Get comprehensive project statistics\n\n### Example Agent Interaction\n\n```\nHuman: \"Show me the latest results from my 'image-classification' project\"\n\nAgent: I'll check your trackio projects and get the latest results.\n\n[Tool: get_projects] → finds \"image-classification\" project\n[Tool: get_runs] → gets runs for \"image-classification\" \n[Tool: get_run_metrics] → gets metrics for latest run\n[Tool: get_available_metrics] → gets metric names\n\nAgent: 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.\n```\n\n## MCP Client Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent:\n\n**Public Spaces:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-space.hf.space/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-private-space.hf.space/gradio_api/mcp/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_HF_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"http://localhost:7860/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\nSee [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.\n\n**Public Spaces:**\n```sh\nclaude mcp add --transport sse trackio https://your-space.hf.space/gradio_api/mcp/sse\n```\n\n**Private Spaces/Datasets:**\n```sh\nclaude mcp add --transport sse --header \"Authorization: Bearer YOUR_HF_TOKEN\" trackio https://your-private-space.hf.space/gradio_api/mcp/sse\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:7860/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nAdd 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.\n\n**Public Spaces:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-space.hf.space/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-private-space.hf.space/gradio_api/mcp/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_HF_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"http://localhost:7860/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) for more info.\n\n**Public Spaces:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"serverUrl\": \"https://your-space.hf.space/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"serverUrl\": \"https://your-private-space.hf.space/gradio_api/mcp/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_HF_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"serverUrl\": \"http://localhost:7860/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eVS Code\u003c/b\u003e\u003c/summary\u003e\n\nAdd to `.vscode/mcp.json`. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n**Public Spaces:**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"trackio\": {\n        \"type\": \"http\",\n        \"url\": \"https://your-space.hf.space/gradio_api/mcp/sse\"\n      }\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"trackio\": {\n        \"type\": \"http\", \n        \"url\": \"https://your-private-space.hf.space/gradio_api/mcp/sse\",\n        \"headers\": {\n          \"Authorization\": \"Bearer YOUR_HF_TOKEN\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"trackio\": {\n        \"type\": \"http\",\n        \"url\": \"http://localhost:7860/gradio_api/mcp/sse\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/summary\u003e\n\nAdd 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.\n\n**Public Spaces:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"https://your-space.hf.space/gradio_api/mcp/sse\"]\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"command\": \"npx\", \n      \"args\": [\"mcp-remote\", \"https://your-private-space.hf.space/gradio_api/mcp/sse\"],\n      \"env\": {\n        \"HF_TOKEN\": \"YOUR_HF_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"http://localhost:7860/gradio_api/mcp/sse\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCline\u003c/b\u003e\u003c/summary\u003e\n\nCreate `.cursor/mcp.json` (or equivalent for your IDE):\n\n**Public Spaces:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-space.hf.space/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n**Private Spaces/Datasets:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"https://your-private-space.hf.space/gradio_api/mcp/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_HF_TOKEN\"\n      }\n    }\n  }\n}\n```\n\n**Local Development:**\n```json\n{\n  \"mcpServers\": {\n    \"trackio\": {\n      \"url\": \"http://localhost:7860/gradio_api/mcp/sse\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n## Configuration\n\n### Environment Variables\n\n- `TRACKIO_DISABLE_MCP`: Set to `\"true\"` to disable MCP functionality (default: MCP enabled)\n\n### Programmatic Control\n\n```python\nimport os\nos.environ[\"TRACKIO_DISABLE_MCP\"] = \"true\"  # Disable MCP\nimport trackio_mcp  # MCP won't be enabled\nimport trackio\n```\n\n## How It Works\n\n`trackio-mcp` uses monkey-patching to automatically:\n\n1. **Enable MCP server**: Sets `mcp_server=True` on all Gradio launches\n2. **Enable API**: Sets `show_api=True` to expose Gradio API endpoints  \n3. **Add tools**: Registers additional trackio-specific MCP tools\n4. **Preserve compatibility**: No changes needed to existing trackio code\n\nThe package patches:\n- `gradio.Blocks.launch()` - Core Gradio launch method\n- `trackio.ui.demo.launch()` - Trackio dashboard launches\n- Adds new MCP endpoints at `/gradio_api/mcp/sse`\n\n## Deployment Examples\n\n### Local Development\n\n```python\nimport trackio_mcp\nimport trackio\n\n# Start local tracking with MCP enabled\ntrackio.show()  # Dashboard + MCP server at http://localhost:7860\n```\n\n### Public Spaces Deployment\n\n```python\nimport trackio_mcp\nimport trackio as wandb\n\n# Deploy to public Spaces with MCP support\nwandb.init(\n    project=\"public-model\",\n    space_id=\"username/model-tracking\"\n)\n\nwandb.log({\"epoch\": 1, \"loss\": 0.5})\nwandb.finish()\n```\n\n### Private Spaces/Datasets Deployment\n\n```python\nimport trackio_mcp\nimport trackio as wandb\n\n# Deploy to private Spaces with private dataset\nwandb.init(\n    project=\"private-model\",\n    space_id=\"organization/private-model-tracking\",  # Private space\n    dataset_id=\"organization/private-model-metrics\"  # Private dataset\n)\n\nwandb.log({\"epoch\": 1, \"loss\": 0.5})\nwandb.finish()\n```\n\n## CLI Interface\n\n```bash\n# Launch standalone MCP server\ntrackio-mcp server --port 7861\n\n# Check status and configuration\ntrackio-mcp status\n\n# Test MCP server functionality\ntrackio-mcp test --url http://localhost:7860\n```\n\n## Security Considerations\n\n- **Private Spaces**: Use HF tokens for authentication with private spaces/datasets\n- **Access Control**: MCP server inherits trackio's access controls\n- **Network Security**: Consider firewall rules for production deployments\n- **Token Management**: Store HF tokens securely, use environment variables\n\n## Troubleshooting\n\n### MCP Server Not Available\n\n```python\nimport trackio_mcp\nimport trackio\n\n# Check if MCP was disabled\nimport os\nprint(\"MCP Disabled:\", os.getenv(\"TRACKIO_DISABLE_MCP\"))\n\n# Manual verification\ntrackio.show()  # Look for MCP server URL in output\n```\n\n### Connection Issues\n\n1. **Check URL**: Ensure correct `/gradio_api/mcp/sse` endpoint\n2. **Authentication**: Add Bearer token for private Spaces/datasets\n3. **Network**: Verify firewall/proxy settings\n4. **Dependencies**: Ensure `gradio[mcp]` is installed\n\n### Tool Discovery Issues\n\n```python\n# Test tools manually\nfrom trackio_mcp.tools import register_trackio_tools\n\ntools = register_trackio_tools()\ntools.launch(mcp_server=True)  # Test tools interface\n```\n\n## Contributing\n\n1. Fork the repository\n2. Install development dependencies: `pip install -e .[dev]`\n3. Make your changes\n4. Run tests: `pytest`\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Acknowledgments\n\n- [trackio](https://github.com/gradio-app/trackio) - The excellent experiment tracking library\n- [Gradio](https://gradio.app) - For built-in MCP server support\n- [Model Context Protocol](https://modelcontextprotocol.io) - For the standardized AI tool protocol\n\n---\n\n**Made with care for the AI research community**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcakyon%2Ftrackio-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffcakyon%2Ftrackio-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffcakyon%2Ftrackio-mcp/lists"}