{"id":51940314,"url":"https://github.com/comet-ml/comet-mcp","last_synced_at":"2026-07-28T18:01:54.688Z","repository":{"id":320253150,"uuid":"1059495298","full_name":"comet-ml/comet-mcp","owner":"comet-ml","description":"An MCP for comet_ml Experiments","archived":false,"fork":false,"pushed_at":"2026-06-01T21:48:52.000Z","size":343,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T10:41:42.253Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/comet-ml.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-18T14:17:59.000Z","updated_at":"2026-06-01T21:48:15.000Z","dependencies_parsed_at":"2025-10-22T20:39:59.472Z","dependency_job_id":"e51f2c4b-8b6c-4e8d-bf0a-8578b8c0a96c","html_url":"https://github.com/comet-ml/comet-mcp","commit_stats":null,"previous_names":["comet-ml/comet-mcp"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/comet-ml/comet-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fcomet-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fcomet-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fcomet-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fcomet-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/comet-ml","download_url":"https://codeload.github.com/comet-ml/comet-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fcomet-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36002533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"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":"2026-07-28T18:01:53.230Z","updated_at":"2026-07-28T18:01:54.648Z","avatar_url":"https://github.com/comet-ml.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Comet ML MCP Server\n\nA comprehensive Model Context Protocol (MCP) server that provides tools for interacting with Comet ML API. This server enables seamless integration with Comet ML's experiment tracking platform through a standardized protocol.\n\n## Features\n\n- **🔧 MCP Server**: Full Model Context Protocol implementation for tool integration\n- **📊 Experiment Management**: List, search, and analyze experiments with detailed metrics\n- **📁 Project Management**: Organize and explore projects across workspaces\n- **🔍 Advanced Search**: Search experiments by name, description, and project\n- **📈 Session Management**: Singleton `comet_ml.API()` instance with robust error handling\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- Comet ML account and API key\n\n### Install from Source\n\n```bash\npip install comet-mcp --upgrade\n```\n\n### Docker Installation (Alternative)\n\nYou can run the Comet MCP server using Docker to avoid installing Python dependencies on your system.\n\n1. **Build the Docker image:**\n   ```bash\n   docker build -t comet-mcp .\n   ```\n\n2. **Configure your MCP client** (see Usage section below for configuration examples)\n\n## Configuration\n\nThe server uses standard comet_ml configuration:\n\n1. Using `comet init`; or\n2. Using environment variables\n\nExample:\n\n```bash\nexport COMET_API_KEY=your_comet_api_key_here\n\n# Optional: Set default workspace (if not provided, uses your default)\nexport COMET_WORKSPACE=your_workspace_name\n```\n\n## Available Tools\n\n### Core Comet ML Tools\n\n- **`list_experiments(workspace, project_name)`** - List recent experiments with optional filtering\n- **`get_experiment_details(experiment_id)`** - Get comprehensive experiment information including metrics and parameters\n- **`get_experiment_code(experiment_id)`** - Retrieve source code from experiments\n- **`get_experiment_output(experiment_id)`** - Get raw training logs (stdout/stderr) from experiments\n- **`get_experiment_metric_data(experiment_ids, metric_names, x_axis)`** - Get metric data for multiple experiments\n- **`get_default_workspace()`** - Get the default workspace name for the current user\n- **`list_projects(workspace)`** - List all projects in a workspace\n- **`list_project_experiments(project_name, workspace)`** - List experiments within a specific project\n- **`count_project_experiments(project_name, workspace)`** - Count and analyze experiments in a project\n- **`get_session_info()`** - Get current session status and connection information\n\n### Tool Features\n\n- **Structured Data**: All tools return properly typed data structures\n- **Error Handling**: Graceful handling of API failures and missing data\n- **Flexible Filtering**: Filter by workspace, project, or search terms\n- **Rich Metadata**: Includes timestamps, descriptions, and status information\n- **File Resources**: Some tools (like `experiment_spreadsheet`) create CSV files that are available as MCP resources\n\n### MCP Resources\n\nThe server provides access to generated files (like CSV exports) through the MCP resources API. When a tool creates a file, it returns a resource URI that can be accessed using the MCP `read_resource` method.\n\n**Accessing Resources:**\n- Tools that create files will return a `resource_uri` in their response\n- Use the MCP `read_resource` method with the URI to read the file content\n- Resources are stored on the server and can be accessed without processing all content through the LLM\n\n**Example:**\n```python\n# After calling experiment_spreadsheet, you'll get a resource_uri\n# Access it using:\nread_resource(uri=\"file://comet-mcp/experiment_spreadsheet_20251206_103508.csv\")\n```\n\nMost MCP clients (like Claude Desktop, Cursor, etc.) will automatically handle resource access when you reference the resource URI in your conversation.\n\n## Usage\n\n### 1. MCP Server Mode\n\nRun the server to provide tools to MCP clients:\n\n```bash\n# Start the MCP server\ncomet-mcp\n```\n\nThe server will:\n- Initialize Comet ML session\n- Register all available tools\n- Listen for MCP client connections via stdio\n\n### 2. Configuration File\n\nCreate a configuration for your AI system. For example:\n\n**Local Installation:**\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"comet-mcp\",\n      \"description\": \"Comet ML MCP server for experiment management\",\n      \"command\": \"comet-mcp\",\n      \"env\": {\n        \"COMET_API_KEY\": \"${COMET_API_KEY}\"\n      }\n    }\n  ]\n}\n```\n\n**Docker Installation (Alternative):**\n```json\n{\n  \"mcpServers\": {\n    \"comet-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"COMET_API_KEY\",\n        \"-e\",\n        \"COMET_WORKSPACE\",\n        \"comet-mcp\",\n        \"comet-mcp\",\n        \"--transport\",\n        \"stdio\"\n      ],\n      \"env\": {\n        \"COMET_API_KEY\": \"your_api_key_here\",\n        \"COMET_WORKSPACE\": \"your_workspace_name\"\n      }\n    }\n  }\n}\n```\n\n`comet-mcp` supports \"stdio\" and \"sse\" transport modes.\n\n\n## 4. Command line options\n\n```\nusage: comet-mcp [-h] [--transport {stdio,sse}] [--host HOST] [--port PORT]\n\nComet ML MCP Server\n\noptions:\n  -h, --help            show this help message and exit\n  --transport {stdio,sse}\n                        Transport method to use (default: stdio)\n  --host HOST           Host for SSE transport (default: localhost)\n  --port PORT           Port for SSE transport (default: 8000)\n```\n\n## 5. OpenTelemetry Observability\n\nThe Comet MCP server includes built-in OpenTelemetry instrumentation for distributed tracing and structured logging. This provides visibility into server operations, tool calls, and Comet ML API interactions.\n\n### Features\n\n- **Distributed Tracing**: Track requests across server operations, tool calls, and API interactions\n- **Structured Logging**: Capture detailed log events with context\n- **Dual Export**: Export telemetry data to both files and Opik (Comet's observability platform)\n- **Low Overhead**: Minimal performance impact with async-friendly instrumentation\n\n### Configuration\n\nTelemetry is enabled by default but can be configured via environment variables.\n\n#### General Configuration\n\n```bash\n# Enable/disable telemetry (default: true)\nexport OTEL_ENABLED=true\n\n# Service name (default: comet-mcp)\nexport OTEL_SERVICE_NAME=comet-mcp\n\n# Service version (default: 1.2.0)\nexport OTEL_SERVICE_VERSION=1.2.0\n```\n\n#### File Export Configuration\n\nExport traces and logs to local files in JSON Lines format:\n\n```bash\n# Path for trace export file (default: traces.jsonl, empty to disable)\nexport OTEL_TRACES_FILE=traces.jsonl\n\n# Path for log export file (default: logs.jsonl, empty to disable)\nexport OTEL_LOGS_FILE=logs.jsonl\n```\n\n**File Format:**\n- Traces: OTLP JSON format, one span per line\n- Logs: Structured JSON format, one log record per line\n- Files are append-only and can be rotated externally\n\n**Example: Reading trace files:**\n```python\nimport json\n\nwith open(\"traces.jsonl\", \"r\") as f:\n    for line in f:\n        span = json.loads(line)\n        print(f\"Span: {span['name']}, Duration: {span['end_time_unix_nano'] - span['start_time_unix_nano']}\")\n```\n\n#### Opik Export Configuration\n\nExport traces and logs to Opik (Comet's observability platform) for cloud-based observability.\n\n**Option 1: Using OTLP Environment Variables**\n\n```bash\n# Opik endpoint\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\n\n# Headers (comma-separated key=value pairs)\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=your-api-key,projectName=your-project,Comet-Workspace=your-workspace\"\n```\n\n**Option 2: Using Individual Variables**\n\n```bash\n# Opik endpoint (defaults to Comet Cloud if not set)\nexport OPIK_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\n\n# Opik API key\nexport OPIK_API_KEY=your-api-key\n\n# Opik project name\nexport OPIK_PROJECT_NAME=your-project\n\n# Comet workspace name\nexport OPIK_WORKSPACE=your-workspace\n```\n\n**For Self-Hosted Opik:**\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://localhost:5173/api/v1/private/otel\"\n```\n\n**For Enterprise Deployment:**\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://\u003ccomet-deployment-url\u003e/opik/api/v1/private/otel\"\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=your-api-key,projectName=your-project,Comet-Workspace=your-workspace\"\n```\n\n### Configuration Examples\n\n**File-only export:**\n```bash\nexport OTEL_TRACES_FILE=traces.jsonl\nexport OTEL_LOGS_FILE=logs.jsonl\n# Opik export disabled (no endpoint configured)\n```\n\n**Opik-only export:**\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\nexport OPIK_API_KEY=your-api-key\nexport OPIK_PROJECT_NAME=your-project\nexport OPIK_WORKSPACE=your-workspace\n# File export disabled (empty file paths)\nexport OTEL_TRACES_FILE=\"\"\nexport OTEL_LOGS_FILE=\"\"\n```\n\n**Both file and Opik export:**\n```bash\n# File export\nexport OTEL_TRACES_FILE=traces.jsonl\nexport OTEL_LOGS_FILE=logs.jsonl\n\n# Opik export\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"https://www.comet.com/opik/api/v1/private/otel\"\nexport OPIK_API_KEY=your-api-key\nexport OPIK_PROJECT_NAME=your-project\nexport OPIK_WORKSPACE=your-workspace\n```\n\n### What Gets Instrumented\n\nThe following operations are automatically instrumented:\n\n- **Server Lifecycle**: Startup, shutdown, session initialization\n- **Tool Operations**: All MCP tool calls (`list_tools`, `call_tool`, `list_resources`, `read_resource`)\n- **Comet ML API Calls**: All tool functions that interact with Comet ML API\n- **Cache Operations**: Cache hits, misses, and writes\n- **Session Management**: Session initialization and API access\n\n### Viewing Traces\n\n**In Opik:**\n1. Navigate to your Opik project\n2. Open the Traces view\n3. Filter by service name: `comet-mcp`\n4. Explore trace spans and their relationships\n\n**From Files:**\n- Use tools like `jq` to parse JSON Lines files:\n  ```bash\n  cat traces.jsonl | jq '.name, .attributes'\n  ```\n- Import into analysis tools that support OTLP JSON format\n- Use log aggregation tools for log files\n\n### Troubleshooting\n\n**Telemetry not appearing:**\n- Check that `OTEL_ENABLED=true` (or not set, defaults to true)\n- Verify file paths are writable (for file export)\n- Check network connectivity (for Opik export)\n- Review server logs for telemetry initialization messages\n\n**Opik export errors:**\n- Verify API key and endpoint are correct\n- Check that project name and workspace match your Opik configuration\n- Ensure you're using HTTP endpoint (not gRPC)\n- Network errors are logged but don't crash the server\n\nFor more information about Opik, see the [Opik OpenTelemetry documentation](https://www.comet.com/docs/opik/integrations/opentelemetry).\n\n## 6. Integration with Opik for use, testing, and optimization\n\nFor complete details on testing this (or any MCP server) see [examples/README](https://github.com/comet-ml/comet-mcp/blob/main/examples/README.md).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [GitHub Repository](https://github.com/comet-ml/comet-mcp)\n- **Issues**: [GitHub Issues](https://github.com/comet-ml/comet-mcp/issues)\n- **Comet ML**: [Comet ML Documentation](https://www.comet.ml/docs/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fcomet-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomet-ml%2Fcomet-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fcomet-mcp/lists"}