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, and manage scenarios (steps)
• Test Plans — create, edit, view associated test cases
• Launches — browse launches and their test results
• Test Results — 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 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) | | 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) | | 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-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 | | 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 |

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:

1. Client — HTTP transport with OAuth authentication and automatic token refresh
2. API — typed methods for each TestOps entity
3. 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