{"id":29115265,"url":"https://github.com/testomatio/mcp","last_synced_at":"2026-05-04T16:02:18.088Z","repository":{"id":297539207,"uuid":"997109142","full_name":"testomatio/mcp","owner":"testomatio","description":"MCP server for Testomat.io","archived":false,"fork":false,"pushed_at":"2026-04-28T14:14:45.000Z","size":180,"stargazers_count":6,"open_issues_count":8,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T16:20:32.629Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://testomat.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testomatio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-06T01:16:37.000Z","updated_at":"2026-04-28T14:21:58.000Z","dependencies_parsed_at":"2025-06-06T02:26:24.970Z","dependency_job_id":"6c14cd96-5ab0-42d2-b840-f267363c43aa","html_url":"https://github.com/testomatio/mcp","commit_stats":null,"previous_names":["testomatio/mcp"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/testomatio/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testomatio","download_url":"https://codeload.github.com/testomatio/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32614385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-06-29T11:07:04.192Z","updated_at":"2026-05-04T16:02:18.081Z","avatar_url":"https://github.com/testomatio.png","language":"JavaScript","funding_links":[],"categories":["Other Tools and Integrations","🌐 Web Development"],"sub_categories":["How to Submit"],"readme":"# Testomat.io MCP Server\n\nModel Context Protocol (MCP) server that enables AI assistants (Claude, Cursor, OpenCode, etc.) to interact with Testomat.io Public API v2.\n\n## Features\n\n- **Full CRUD** for core entities:\n  - Tests, Suites, Plans, Runs, TestRuns, RunGroups, Steps, Snippets, Labels\n  - Tags and Milestones (read-only access)\n  - Issues (global + scoped helpers for tests/suites/runs/testruns/plans)\n  - Requirements (including file uploads from local file paths)\n- **Smart Search** - delegates to list endpoints with OpenAPI-aligned query/filter forwarding\n- **Issue Linking** - link/unlink issues to any resource\n- **API Compatibility** - automatic handling of payload format differences (flat vs wrapped)\n- **Automatic API Sessions** - groups MCP changes in Testomat.io history using API sessions\n- **Run Management** - status transitions via `status_event` parameter\n- **TQL-Only Search** - `tests_list/tests_search` and `runs_list/runs_search` use `tql` as the single search/filter input\n- **Built-In TQL Reference** - MCP tool descriptions include exact TQL fields, syntax, and examples for agents\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install -g @testomatio/mcp@latest\n```\n\nNeed enterprise analytics tools? Install `@testomatio/mcp-enterprise@latest` instead. Details are in the `Enterprise Analytics` section below.\n\n### Configuration\n\n**Required credentials:**\n- `TESTOMATIO_PROJECT_TOKEN` - Your project API token\n- `TESTOMATIO_PROJECT_ID` - Your project ID\n\n**Run server:**\n```bash\ntestomatio-mcp --token \u003cPROJECT_TOKEN\u003e --project \u003cPROJECT_ID\u003e\n```\n\n**Or with environment variables:**\n```bash\nexport TESTOMATIO_PROJECT_TOKEN=\u003cPROJECT_TOKEN\u003e\nexport TESTOMATIO_PROJECT_ID=\u003cPROJECT_ID\u003e\ntestomatio-mcp\n```\n\n**Optional: custom base URL**\n```bash\nexport TESTOMATIO_BASE_URL=https://beta.testomat.io\n```\n\n## Usage with AI Assistants\n\n### Cursor IDE\n\nAdd this config to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for global access:\n\n```json\n{\n  \"mcpServers\": {\n    \"testomatio\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@testomatio/mcp@latest\",\n        \"--token\",\n        \"\u003cTOKEN\u003e\",\n        \"--project\",\n        \"\u003cPROJECT_ID\u003e\"\n      ],\n      \"env\": {\n        \"TESTOMATIO_BASE_URL\": \"https://app.testomat.io\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd this config to:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"testomatio\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@testomatio/mcp@latest\",\n        \"--token\",\n        \"\u003cTOKEN\u003e\",\n        \"--project\",\n        \"\u003cPROJECT_ID\u003e\"\n      ],\n      \"env\": {\n        \"TESTOMATIO_BASE_URL\": \"https://app.testomat.io\"\n      }\n    }\n  }\n}\n```\n\n### OpenCode\n\nAdd this config to `opencode.json` in your project root, or to `~/.config/opencode/opencode.json` for global access:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"testomat\": {\n      \"type\": \"local\",\n      \"command\": [\n        \"npx\",\n        \"-y\",\n        \"@testomatio/mcp@latest\",\n        \"--token\",\n        \"\u003cTOKEN\u003e\",\n        \"--project\",\n        \"\u003cPROJECT_ID\u003e\"\n      ],\n      \"enabled\": true,\n      \"environment\": {\n        \"TESTOMATIO_BASE_URL\": \"https://app.testomat.io\"\n      }\n    }\n  }\n}\n```\n\n## Quick Examples\n\n**List tests:**\n```json\n{\n  \"name\": \"tests_list\",\n  \"arguments\": { \"page\": 1, \"per_page\": 50, \"tql\": \"priority == 'high'\" }\n}\n```\n\n**Create test:**\n```json\n{\n  \"name\": \"tests_create\",\n  \"arguments\": {\n    \"title\": \"User login test\",\n    \"suite_id\": \"123\",\n    \"priority\": \"high\"\n  }\n}\n```\n\n**Create run:**\n```json\n{\n  \"name\": \"runs_create\",\n  \"arguments\": {\n    \"title\": \"Smoke tests\",\n    \"kind\": \"automated\",\n    \"env\": \"production\"\n  }\n}\n```\n\n**Finish run:**\n```json\n{\n  \"name\": \"runs_update\",\n  \"arguments\": {\n    \"run_id\": \"456\",\n    \"status_event\": \"finish\"\n  }\n}\n```\n\n## Documentation\n\nComplete tool reference: [docs/tools.md](./docs/tools.md)\n\n## Project Structure\n\n```text\nsrc/\n|- config/          # Config loading, defaults\n|- core/            # Errors, logger\n|- api/             # HTTP client, Testomat.io API client\n|- mcp/             # MCP server, tools, registry\n|  |- definitions/  # Tool definitions by entity\n|  |- configs/      # Registry generation configs\n|  `- registry/     # Tool handlers\n`- cli/             # CLI bootstrap\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `TESTOMATIO_PROJECT_TOKEN` | Yes* | - | Project token (preferred) |\n| `TESTOMATIO_API_TOKEN` | Yes* | - | Alternative token |\n| `TESTOMATIO_PROJECT_ID` | Yes | - | Project ID |\n| `TESTOMATIO_BASE_URL` | No | `https://app.testomat.io` | API base URL |\n\n*Either `TESTOMATIO_PROJECT_TOKEN` or `TESTOMATIO_API_TOKEN`\n\n## Corporate TLS Certificates\n\nIf the MCP server runs behind a corporate proxy or TLS inspection, Node.js may reject Testomat.io HTTPS requests even when the same URL works in a browser. This usually means the company root certificate is trusted by the operating system, but not by Node.js.\n\nUse Node.js system CA support:\n\n```bash\nNODE_OPTIONS=--use-system-ca testomatio-mcp --token \u003cTOKEN\u003e --project \u003cPROJECT_ID\u003e\n```\n\nFor MCP clients, pass `NODE_OPTIONS` in the server environment:\n\n```json\n{\n  \"mcpServers\": {\n    \"testomatio\": {\n      \"command\": \"testomatio-mcp\",\n      \"args\": [\"--token\", \"\u003cTOKEN\u003e\", \"--project\", \"\u003cPROJECT_ID\u003e\"],\n      \"env\": {\n        \"NODE_OPTIONS\": \"--use-system-ca\"\n      }\n    }\n  }\n}\n```\n\nIf your Node.js version does not support `--use-system-ca`, export the corporate root certificate to a PEM file and use Node.js extra CA support:\n\n```bash\nNODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token \u003cTOKEN\u003e --project \u003cPROJECT_ID\u003e\n```\n\n## Important Notes\n\n- **Run Status** - Use `runs_update` with `status_event` for transitions (finish, launch, rerun, etc.)\n- **Search** - No dedicated `/search` endpoints. MCP search tools delegate to list tools; for `tests` and `runs` the MCP interface is intentionally simplified to `tql`, while other entities stay closer to Public API v2 filters\n- **TQL** - Use `tql` as the single search/filter input for `tests_list/tests_search` and `runs_list/runs_search`\n- **TQL Syntax** - For user-facing syntax details and more examples, see the official TQL docs: https://docs.testomat.io/advanced/tql/\n- **TQL Scope** - The full agent-oriented whitelist of documented fields lives inside MCP tool descriptions for `tests` and `runs`\n- **Issue Linking** - Scoped helpers available: `{entity}_issues_link/unlink`\n- **Enterprise Package** - Analytics tools are intentionally exposed only by `@testomatio/mcp-enterprise`, not by the standard `@testomatio/mcp` package\n- **API Sessions** - The server automatically starts a Testomat.io session before the first `POST`, `PUT`, or `DELETE` request, sends the returned session hash as `X-Session-Hash` on later mutating requests, and stops the session when the MCP server shuts down. `GET` requests do not start or use sessions.\n\n## Development\n\n```bash\nnpm install\nnpm run start -- --token \u003cTOKEN\u003e --project \u003cPROJECT_ID\u003e\n```\n\nFor local MCP development, point Claude Desktop to the checked-out entrypoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"testomatio-local\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp/index.js\", \"--token\", \"\u003cTOKEN\u003e\", \"--project\", \"\u003cPROJECT_ID\u003e\"]\n    }\n  }\n}\n```\n\n## Enterprise Analytics\n\nEnterprise analytics is available only in the separate `@testomatio/mcp-enterprise` package.\n\nInstallation:\n\n```bash\nnpm install -g @testomatio/mcp-enterprise@latest\n```\n\nRun:\n\n```bash\ntestomatio-mcp-enterprise --token \u003cPROJECT_TOKEN\u003e --project \u003cPROJECT_ID\u003e\n```\n\nIncluded tools:\n\n- `analytics_tests` - `GET /api/v2/{project_id}/analytics/tests/{kind}`\n- `analytics_stats` - `GET /api/v2/{project_id}/analytics/stats/{kind}`\n\nAnalytics endpoints require the `api_analytics` subscription feature. Use `q` as the TQL filter parameter for analytics tools.\n\nExample `analytics_tests` call:\n\n```json\n{\n  \"name\": \"analytics_tests\",\n  \"arguments\": {\n    \"kind\": \"flaky\",\n    \"q\": \"priority == 'high'\",\n    \"days\": 30,\n    \"page\": 1,\n    \"per_page\": 20\n  }\n}\n```\n\nExample `analytics_stats` call:\n\n```json\n{\n  \"name\": \"analytics_stats\",\n  \"arguments\": {\n    \"kind\": \"success-rate-by-date\",\n    \"q\": \"tag IN ['@smoke']\",\n    \"from\": \"2026-04-01\",\n    \"to\": \"2026-04-30\"\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestomatio%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestomatio%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestomatio%2Fmcp/lists"}