Testomatio MCP Server

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

Install via npm

Or run directly with npx

Usage

Command Line Options

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

Using Command Line Arguments

Using Environment Variables

Getting Your API Token

1. Go to Testomat.io
2. Navigate to user tokens https://app.testomat.io/account/access_tokens
3. 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:

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):

Option 2: Using Environment Variables

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

Then add this to your Cursor MCP settings:

Option 3: Global Installation

If you've installed the package globally:

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-Based Searches

Tags can be searched using the @ prefix:

Jira Integration

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

Troubleshooting

Common Issues

1. "API token is required" error
   • Make sure your token starts with testomat_
   • Verify the token is correct in your Testomat.io project settings
2. "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
3. 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
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 to test

Debug Mode

To see detailed logs when running the server:

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:

1. Check 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