TestOps MCP Server

An MCP server that connects AI agents (Claude, Cursor, etc.) to TestOps — enabling test case management, launches, defects, and analytics through natural language.

Features

Projects — list and inspect projects
Test Cases — create, read, update, delete, search by AQL, inspect run history, and manage scenarios (steps, attachments, shared steps)
Test Plans — create, edit, view associated test cases
Launches — browse launches, their progress, and their test results
Test Results — view run history, view and update statuses
Defects — create, edit, browse
Analytics — automation trend, status distribution, success rate
Read-only mode — disable all write operations for safe environments

Quick Start

Prerequisites

Node.js 20+
Access to a TestOps instance
TestOps API token

Installation

npm install -g testops-mcp

MCP Client Configuration

Add to your MCP client config (Claude Desktop, Cursor, Claude Code, etc.):

{
  "mcpServers": {
    "testops": {
      "command": "testops-mcp",
      "env": {
        "TESTOPS_URL": "https://your-testops-instance.example.com",
        "TESTOPS_TOKEN": "your-api-token"
      }
    }
  }
}

Or with npx (no global install required):

{
  "mcpServers": {
    "testops": {
      "command": "npx",
      "args": ["-y", "testops-mcp"],
      "env": {
        "TESTOPS_URL": "https://your-testops-instance.example.com",
        "TESTOPS_TOKEN": "your-api-token"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |---|---|---| | TESTOPS_URL | Yes | TestOps instance URL (e.g. https://testops.example.com) | | TESTOPS_TOKEN | Yes | API token for authentication | | TESTOPS_PROJECT_ID | No | Default project ID (so you don't have to specify it in every request) | | TESTOPS_PAGE_SIZE | No | Pagination page size (server default if not set) | | TESTOPS_READ_ONLY | No | Set to true to disable all write operations | | TESTOPS_TIMEOUT_MS | No | Request timeout in milliseconds for auth and API calls (default: 30000) | | TESTOPS_RETRY_MAX | No | Retry count for transient read-request failures (default: 2) | | TESTOPS_RETRY_BASE_MS | No | Base backoff delay in milliseconds for transient read-request retries (default: 250) | | TESTOPS_LOG_LEVEL | No | Runtime stderr log level: error, info, or debug (default: error) | | TESTOPS_LOG_FORMAT | No | Runtime stderr log format: json or pretty (default: json) |

Available Tools

Projects

| Tool | Description | |---|---| | list-projects | List all projects | | get-project | Get project details by ID |

Test Cases

| Tool | Description | |---|---| | list-test-cases | List test cases in a project | | search-test-cases | Search test cases by AQL query | | get-test-case | Get test case basic details | | get-test-case-overview | Get full test case details (members, issues, custom fields, requirements, test keys) | | get-test-case-history | Get past runs of a test case across launches (status, launch, failure message) | | create-test-case | Create a test case (with tags, links, members) | | update-test-case | Update a test case (with tags, links, members, duration) | | delete-test-case | Delete a test case | | get-test-case-scenario | Get test case steps (Gherkin scenarios + manual UI steps, with attachments and expanded shared steps) | | update-test-case-scenario | Update test case scenario |

Test Case Sub-Resources

| Tool | Description | |---|---| | get-test-case-issues | Get issue links (Jira, YouTrack, etc.) | | set-test-case-issues | Set issue links for a test case | | get-test-case-members | Get members (owner, reviewers) | | set-test-case-members | Set members for a test case | | get-test-case-custom-fields | Get custom field values (Component, Priority, Team, etc.) | | set-test-case-custom-fields | Update custom field values | | get-test-case-relations | Get relations (related to, clones, duplicates, etc.) | | set-test-case-relations | Set relations for a test case | | get-test-case-requirements | Get linked requirements | | set-test-case-requirements | Set requirements for a test case | | get-test-case-test-keys | Get test keys | | set-test-case-test-keys | Set test keys for a test case |

Test Plans

| Tool | Description | |---|---| | list-test-plans | List test plans | | get-test-plan | Get test plan details | | create-test-plan | Create a test plan | | update-test-plan | Update a test plan | | get-test-plan-test-cases | Get test cases in a test plan |

Launches

| Tool | Description | |---|---| | list-launches | List launches | | get-launch | Get launch details | | get-launch-progress | Get whether a launch has finished, plus its status counts | | get-launch-test-results | Get test results for a launch |

Test Results

| Tool | Description | |---|---| | list-test-results | List test results | | get-test-result | Get test result details | | get-test-result-history | Get previous runs of the same test (stable failure vs flaky) | | update-test-result | Update a test result |

Defects

| Tool | Description | |---|---| | list-defects | List defects | | get-defect | Get defect details | | create-defect | Create a defect | | update-defect | Update a defect |

Analytics

| Tool | Description | |---|---| | get-automation-trend | Test automation trend over time | | get-status-distribution | Test status distribution | | get-success-rate | Test success rate |

Reference Data

| Tool | Description | |---|---| | list-test-layers | List available test layers (UI, API, Unit, etc.) with IDs | | list-workflows | List workflows with their statuses and IDs | | list-project-custom-fields | List custom fields configured for a project, with IDs | | list-custom-field-values | List the values a custom field can take in a project (requires customFieldId) |

Architecture

src/
├── index.ts                 # Entry point: MCP server initialization
├── config.ts                # Environment variable configuration
├── client/
│   ├── auth.ts              # OAuth authentication with JWT token caching
│   └── http-client.ts       # HTTP client with automatic token injection
├── api/                     # Typed API clients
│   ├── projects.ts
│   ├── test-cases.ts
│   ├── test-plans.ts
│   ├── launches.ts
│   ├── test-results.ts
│   ├── defects.ts
│   ├── analytics.ts
│   └── reference-data.ts
├── tools/                   # MCP tool registration
│   ├── register-all.ts
│   ├── projects.ts
│   ├── test-cases.ts
│   ├── test-plans.ts
│   ├── launches.ts
│   ├── test-results.ts
│   ├── defects.ts
│   ├── analytics.ts
│   └── reference-data.ts
├── types/                   # TypeScript interfaces
│   ├── common.ts
│   └── api-types.ts
└── utils/
    ├── formatting.ts        # API response formatting for LLM readability
    └── error-handler.ts     # Tool error handling wrapper

Three-layer design:

Client — HTTP transport with OAuth authentication and automatic token refresh
API — typed methods for each TestOps entity
Tools — MCP tools with Zod parameter validation and response formatting

Development

git clone <repo-url>
cd testops-mcp
npm install        # also installs pre-commit hook via "prepare" script
npm run build
npm start

Testing

The project has 220 unit tests covering all layers (utils, config, client, API, tools).

npm test           # run all tests once
npm run test:watch # run in watch mode
npm run check      # lint + unit tests + build + docs/guardrail checks
npm run contract:drift # ensure fake backend route contracts match src/api/*
npm run eval:smoke # run end-to-end smoke eval against a fake local TestOps backend
npm run eval:matrix # run full local eval matrix across all tool groups and logging modes

A pre-commit hook automatically runs the test suite before every commit. If any test fails, the commit is blocked.

CI

GitHub Actions runs on every push to main and on every pull request.

check runs on Node 20 and Node 22
eval:smoke runs on Node 20
eval:matrix runs on Node 20

The workflow file lives at .github/workflows/ci.yml.

Diagnostics

Runtime diagnostics are emitted to stderr only so they do not interfere with MCP stdout transport.

Examples:

TESTOPS_LOG_LEVEL=info TESTOPS_LOG_FORMAT=json testops-mcp
TESTOPS_LOG_LEVEL=debug TESTOPS_LOG_FORMAT=pretty testops-mcp

If the MCP client does not surface subprocess stderr clearly, reproduce the same server config in a terminal and inspect the logs there. Detailed guidance lives in docs/logging.md.

Repo Knowledge Base

Agent-facing repository guidance lives in:

AGENTS.md
docs/index.md
docs/architecture.md
docs/reliability.md
docs/security.md
docs/logging.md
docs/runbooks.md
docs/evals.md

License

MIT

TestOps MCP Server