MCP

🚀 Testomat.io MCP Server

A Model Context Protocol (MCP) server for integrating Testomat.io API with AI assistants such as Cursor.

🚀 Quick Start

The Testomat.io MCP Server enables seamless integration between the Testomat.io API and AI assistants like Cursor. Follow the steps below to get started.

✨ Features

Tools

Tests

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

Test Suites

• search_suites – Search for 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 a single suite (params: suite_id) — api: GET /suites/{suite_id}

Test Runs

• get_runs – List all runs (no params) — api: GET /runs
• get_run – Get a single run (params: run_id, tree) — api: GET /runs/{run_id}
• get_testruns – Retrieve 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 a single plan (params: plan_id) — api: GET /plans/{plan_id}

📦 Installation

Prerequisites

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

Install via npm

npm install -g @testomatio/mcp

Or run directly with npx

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

💻 Usage Examples

Command Line Options

The MCP server can be launched 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

# If installed globally
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

1. Navigate to Testomat.io.
2. Go to user tokens at https://app.testomat.io/account/access_tokens.
3. Create and copy the General API token (starting with testomat_).

Getting Your Project ID

You can find your project ID in the URL when 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": ["@testomatio/mcp", "--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": ["@testomatio/mcp", "--project", "YOUR_PROJECT_ID"],
      "env": {
        "TESTOMATIO_API_TOKEN": "testomat_YOUR_TOKEN_HERE"
      }
    }
  }
}

Option 3: Global Installation

If you've installed the package globally:

{
  "mcpServers": {
    "testomatio": {
      "command": "testomatio-mcp",
      "args": ["--token", "testomat_YOUR_TOKEN_HERE", "--project", "YOUR_PROJECT_ID"]
    }
  }
}

Example Usage in Cursor

Once configured, you can pose questions to your AI assistant, such as:

• "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 are used to retrieve general information without specific filtering:

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

Specific Item Queries

These queries target specific entities by ID:

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

Search and Filter Queries

These queries leverage advanced filtering capabilities:

• "List all automated tests with the @smoke tag" → Use the search_tests tool with query: "@smoke", state: "automated"
• "Find tests with priority high" → Use the search_tests tool with priority: "high"
• "Search for tests containing 'login'" → Use the search_tests tool with query: "login"
• "List tests tagged @critical or labelled 'ux' with high priority" → Use the search_tests tool with tql: "tag == 'critical' or label == 'ux' and priority == 'high'"
• "Find tests linked to JIRA-123" → Use the 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

1. "API token is required" error

   • Ensure your token starts with testomat_.
   • Verify the token's accuracy in your Testomat.io project settings.

2. "Project ID is required" error

   • Check that you're passing the correct project ID.
   • Confirm the project ID exists and you have access to it.

3. Connection errors

   • Ensure you have an active internet connection.
   • Check if your firewall permits connections to app.testomat.io.
   • Verify that your API token has the necessary permissions.

4. 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 for testing.

Debug Mode

To view detailed logs when running the server:

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

📚 Documentation

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

🔧 Technical Details

This project offers a Model Context Protocol (MCP) server for integrating the Testomat.io API with AI assistants. It supports all major Testomat.io API endpoints, provides an MCP-compatible tool interface, and uses semantic XML formatting for LLM processing.

📄 License

This project is licensed under the MIT License. For detailed information, refer to the LICENSE file.

Support

For support, please follow these steps:

1. Consult the Testomat.io Documentation.
2. Open an issue on GitHub.
3. 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