Testomat.io MCP Server

A Model Context Protocol (MCP) server for Testomat.io API integration with AI assistants like Cursor.

Installation

Prerequisites

Node.js 18 or higher (with built-in fetch support)
npm or yarn package manager
Testomat.io account with API access

Run directly with npx

npx @testomatio/mcp --token <your-token> --project <project-id>

Usage

Command Line Options

The MCP server can be started using command line arguments or environment variables:

Using Command Line Arguments

# Using short flags
npx @testomatio/mcp -t testomat_YOUR_TOKEN_HERE -p your-project-id

# Using long flags
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id

# With custom base URL
npx @testomatio/mcp --token testomat_YOUR_TOKEN_HERE --project your-project-id --base-url https://your-instance.testomat.io

Using Environment Variables

# Set environment variables
export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE
export TESTOMATIO_BASE_URL=https://app.testomat.io  # Optional, defaults to https://app.testomat.io

# Run with project ID
npx @testomatio/mcp --project your-project-id

# Or run directly with environment variables
TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE npx @testomatio/mcp --project your-project-id

Getting Your API Token

Go to Testomat.io
Navigate to user tokens https://app.testomat.io/account/access_tokens
Create and copy General API token (starts with testomat_)

Getting Your Project ID

Your project ID can be found in the URL when you're viewing your project:

https://app.testomat.io/projects/YOUR_PROJECT_ID

Integration with Cursor

To use this MCP server with Cursor, add the following configuration to your Cursor settings:

Option 1: Using npx (Recommended)

Add this to your Cursor MCP settings (cursor-settings.json or through the Cursor settings UI):

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["-y", "@testomatio/mcp@latest", "--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
    }
  }
}

Option 2: Using Environment Variables

First, set your environment variables in your shell profile (.bashrc, .zshrc, etc.):

export TESTOMATIO_API_TOKEN=testomat_YOUR_TOKEN_HERE

Then add this to your Cursor MCP settings:

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": ["-y", "@testomatio/mcp@latest", "--project", "YOUR_PROJECT_ID"],
      "env": {
        "TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Features

Tools

Tests

get_tests – Get all tests (params: plan, query, state, suite_id, tag, labels) — api: GET /tests
search_tests – Search tests (params: query, tql, labels, state, priority, filter, page) — api: GET /tests

Test Suites

search_suites – Search suites (params: query, labels, state, priority, page) — api: GET /suites
get_root_suites – List root-level suites (no params) — api: GET /suites
get_suite – Get one suite (params: suite_id) — api: GET /suites/{suite_id}

Test Runs

get_runs – List all runs (no params) — api: GET /runs
get_run – Get one run (params: run_id, tree) — api: GET /runs/{run_id}
get_testruns – Runs for a test (params: test_id, finished_at_date_range) — api: GET /testruns

Test Plans

get_plans – List all plans (params: detail, labels, page) — api: GET /plans
get_plan – Get one plan (params: plan_id) — api: GET /plans/{plan_id}

Example Usage in Cursor

Once configured, you can ask your AI assistant questions like:

"Show me all the tests in the project"
"Get the test runs for test ID abc123"
"What are the root suites in this project?"
"Show me details for test run xyz789"
"List all automated tests with the @smoke tag"
"Get all test plans for this project"

Query Patterns

Basic Information Queries

These queries retrieve general information without specific filtering:

"Show me all the tests in the project" → get_tests tool
"What are the root suites in this project?" → get_root_suites tool
"Get all test runs" → get_runs tool
"Get all test plans for this project" → get_plans tool

Specific Item Queries

These queries target specific entities by ID:

"Get test runs for test ID abc123" → get_testruns tool with test_id: "abc123"
"Show me details for test run xyz789" → get_run tool with run_id: "xyz789"
"Get suite details for suite-456" → get_suite tool with suite_id: "suite-456"

Search and Filter Queries

These queries use advanced filtering capabilities:

"List all automated tests with the @smoke tag" → search_tests tool with query: "@smoke", state: "automated"
"Find tests with priority high" → search_tests tool with priority: "high"
"Search for tests containing 'login'" → search_tests tool with query: "login"
"List tests tagged @critical or labelled 'ux' with high priority" → search_tests tool with tql: "tag == 'critical' or label == 'ux' and priority == 'high'"
"Find tests linked to JIRA-123" → search_tests tool with tql: jira == 'BDCP-2'

Advanced Query Syntax

Test Query Language (TQL)

The search_tests tool supports TQL for complex filtering:

"tag == 'smoke' and state == 'manual'"
"priority == 'high' or label == 'ux'"

Tag-Based Searches

Tags can be searched using the @ prefix:

@smoke        # Tests tagged with 'smoke'
@regression   # Tests tagged with 'regression'
@critical     # Tests tagged with 'critical'

Jira Integration

Tests linked to Jira issues can be found using issue keys:

JIRA-123      # Tests linked to JIRA-123
PROJ-456      # Tests linked to PROJ-456

Troubleshooting

Common Issues

"API token is required" error
- Make sure your token starts with testomat_
- Verify the token is correct in your Testomat.io project settings
"Project ID is required" error
- Check that you're passing the correct project ID
- Verify the project ID exists and you have access to it
Connection errors
- Ensure you have internet connectivity
- Check if your firewall allows connections to app.testomat.io
- Verify your API token has the necessary permissions
MCP server not starting in Cursor
- Check Cursor's MCP logs for error messages
- Ensure Node.js 18+ is installed and accessible
- Try running the command manually first to test

Debug Mode

To see detailed logs when running the server:

DEBUG=* npx @testomatio/mcp --token <token> --project <project-id>

API Reference

For detailed information about the underlying Testomat.io API, refer to the Testomat.io API Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please:

Check the Testomat.io Documentation
Open an issue on GitHub
Contact Testomat.io support

Changelog

v1.0.0

Initial release
Support for all major Testomat.io API endpoints
MCP-compatible tool interface
Semantic XML formatting for LLM processing