ReportPortal MCP Server

> Documentation note: This README reflects the current development branch. For the available up-to-date list of tools and capabilities, check the README on the main branch.

What is the ReportPortal MCP Server?

The ReportPortal MCP Server is a bridge between your ReportPortal instance and AI chat assistants (such as Claude Desktop, GitHub Copilot, Cursor). In simple terms, it lets you ask questions in plain English about your test runs and get answers directly from ReportPortal. It follows the official MCP guidelines.

Starting with version 2.x, the server also integrates with the ReportPortal Test Case Management System (TMS) — test cases, folders, milestones, and test plans — so you can browse and manage test design data through the same chat interface.

For example, instead of logging into the ReportPortal UI, you could ask your AI assistant "What tests failed in the last run?" or "List the 5 most recent test runs," and it will fetch that information from ReportPortal for you. <br/> With TMS support, you can also ask things like "List test cases in the Smoke folder" or "Create a test plan for the current sprint milestone." This makes it easy for QA testers and managers to manage test cases, query test results and test assets using natural language, speeding up planning, analysis and reporting.

Why Use It?

- Quick Test Insights: Instantly retrieve summaries of test runs, failure counts, or error details without writing code or navigating the UI.
- TMS from Chat: Browse, create, and update test cases, folders, milestones, and test plans in ReportPortal TMS without leaving your AI assistant.
- Chat-Based Queries: Use your favourite AI assistant (Claude, Cursor, etc.) to converse with ReportPortal data. It's like having a smart test-reporting helper in your chat window.
- Integration Flexibility: Works with any MCP-compatible AI tool. You simply point the tool at this server and it can run ReportPortal queries under the hood.
- No Custom Scripts Needed: Common queries (listing runs, getting failures, analysis, TMS lookups) are built-in as simple "commands" you invoke via chat.

Prerequisites

Before setting up the MCP server, you need the following information from your ReportPortal instance:

ReportPortal Host URL (RP_HOST)

The URL of your ReportPortal instance:
- Example: https://reportportal.example.com
- For local: http://localhost:8080

Project Key (RP_PROJECT) — Optional

This value is optional. When set, it defines the default project key used for all requests. The projectKey tool argument is only used as a fallback when no project is available from the context (i.e. RP_PROJECT env variable in stdio mode, or the X-Project HTTP header in HTTP mode).

The project key is the unique project identifier within the ReportPortal instance, do not use the project display name as project key. Find this on the ReportPortal general settings page:

https://your-rp-instance.com/ui/#organizations/{your-organization}/projects/{your_project}/settings/general

API Token (RP_API_TOKEN)

You can get an API token from your ReportPortal Profile or generate a new one.
Security Note: Never commit tokens to version control or share them publicly.

Server Mode (MCP_MODE)

MCP_MODE is a system environment variable that controls the transport mode of the MCP server:

| Value | Description |
|-------|-------------|
| stdio | (default) Standard input/output – used for local AI tool integrations (Claude Desktop, Cursor, VS Code Copilot, etc.) |
| http | HTTP/SSE streaming – exposes an HTTP endpoint for remote or multi-client access |

This variable is only needed when you want to run the server in HTTP mode. For local AI tool integrations the default stdio mode is used and no extra configuration is required.

> Important: http mode is intended for server deployments. The MCP server must be deployed and running with MCP_MODE=http before any AI tool can connect to it remotely. See the For developers section for deployment instructions.

<a name="installation"></a>

Installation

There are two ways to connect to the ReportPortal MCP Server:
1. Locally - via Docker (recommended) or using pre-built binaries.
2. Connecting to a remote MCP server (when the server is already deployed)

Each of these methods is suitable for any LLM provider.

Local installation

The configurations below use the default stdio mode (MCP_MODE=stdio), which is the correct choice for all local AI tool integrations. To run the server in HTTP mode instead, add MCP_MODE=http to the env block (see the For developers section for details).

Via Docker (recommended)

The MCP server is available on the official ReportPortal's DockerHub.

Configuration:

{

  "reportportal": {

    "command": "docker",

    "args": [

      "run",

      "-i",

      "--rm",

      "-e",

      "RP_API_TOKEN",

      "-e",

      "RP_HOST",

      "-e",

      "RP_PROJECT",

      "reportportal/mcp-server"

    ],

    "env": {

      "RP_API_TOKEN": "your-api-token",

      "RP_HOST": "https://your-reportportal-instance.com",

      "RP_PROJECT": "YourProjectKeyFromReportPortal"

    }

  }

}

Using pre-built binaries

The OS pre-built binaries can be downloaded from the official releases on GitHub.

Configuration:

{

  "reportportal": {

    "command": "/path/to/reportportal-mcp-server-binary",

    "args": ["stdio"],

    "env": {

      "RP_API_TOKEN": "your-api-token",

      "RP_HOST": "https://your-reportportal-instance.com",

      "RP_PROJECT": "YourProjectKeyFromReportPortal"

    }

  }

}

Connecting to a Remote MCP Server

If the ReportPortal MCP Server is already deployed and accessible via HTTP, you can connect to it remotely without running it locally. This is useful when the server is hosted centrally or in a shared environment.

> Note: The remote server must be deployed and running in HTTP mode (system environment variable MCP_MODE=http) before any AI tool can connect to it. See the For developers section for deployment and configuration details.

Remote Server Configuration:

{
  "reportportal": {
    "url": "http://your-mcp-server-host:port/mcp",
    "headers": {
      "Authorization": "Bearer ${RP_API_TOKEN}",
      "X-Project": "YourProjectKeyFromReportPortal"
    }
  }
}

Configuration Parameters:
- url: The HTTP endpoint URL of the remote MCP server (use /mcp or /api/mcp)
- headers.Authorization: Bearer token for authentication (required)
- headers.X-Project: The ReportPortal project key — the unique project identifier, not the display name (optional)

AI Tool Setup

Choose your favourite AI Tool to connect.

Cursor (AI Code Editor)

Just click

Or follow the next steps:

1. In Cursor, go to Settings then Tools & MCP and click Add Custom MCP.
2. That will open file mcp.json where you need to add a new MCP server entry that runs the ReportPortal MCP Server:

For local installation (Docker or binary):

> Choose your preferred configuration from the Installation section and paste it inside the reportportal block.

{
  "mcpServers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

For remote server:

> Note: The remote server must be deployed and running in HTTP mode before connecting.

{
  "mcpServers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "headers": {
        "Authorization": "Bearer ${RP_API_TOKEN}",
        "X-Project": "YourProjectKeyFromReportPortal"
      }
    }
  }
}

Documentation: Cursor MCP.

GitHub Copilot (In VS Code and JetBrains IDEs)

VS Code

1. Install/update the GitHub Copilot plugin.
2. Press Ctrl+P and type >mcp in the search bar and select MCP: Open User Configuration.
3. That will open file mcp.json where you need to add a new MCP server entry that runs the ReportPortal MCP Server:

For local installation (Docker or binary):

> Choose your preferred configuration from the Installation section and paste it inside the reportportal block.

{
  "servers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

For remote server:

> Note: The remote server must be deployed and running in HTTP mode before connecting.

{
  "servers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer ${RP_API_TOKEN}",
          "X-Project": "YourProjectKeyFromReportPortal"
        }
      }
    }
  }
}

Documentation: VS Code Copilot Guide.

JetBrains IDEs

1. Install/update the GitHub Copilot plugin.
2. Click GitHub Copilot icon in the status bar → Edit Settings → Model Context Protocol → Configure.
3. Add configuration:

For local installation (Docker or binary):

> Choose your preferred configuration from the Installation section and paste it inside the reportportal block.

{
  "servers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

For remote server:

> Note: The remote server must be deployed and running in HTTP mode before connecting.

{
  "servers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer ${RP_API_TOKEN}",
          "X-Project": "YourProjectKeyFromReportPortal"
        }
      }
    }
  }
}

4. Press Ctrl + S or Command + S to save, or close the mcp.json file. The configuration should take effect immediately and restart all the MCP servers defined. You can restart the IDE if needed.

Documentation: JetBrains Copilot Guide.

Claude Desktop

1. Open Claude Desktop, go to Settings → Developer → Edit Config.
2. Add a new MCP server entry that runs the ReportPortal MCP Server.

For local installation (Docker or binary):

> Choose your preferred configuration from the Installation section and paste it inside the reportportal block.

{
  "mcpServers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

3. Save and restart Claude Desktop.

For remote server:

Claude Desktop does not natively support direct Server-Sent Events (SSE) transport for remote Model Context Protocol (MCP) servers, as it is designed to communicate primarily via local standard I/O (stdio). To connect to a remote SSE server, you must use a local wrapper script or bridging tool (e.g., mcp-remote, npx) in your claude_desktop_config.json to bridge stdio to SSE.

Claude Code CLI

1. Open your terminal.
2. Run one of the following commands.

For local installation (Docker):

claude mcp add-json reportportal '{"command": "docker", "args": ["run", "-i", "--rm", "-e", "RP_API_TOKEN", "-e", "RP_HOST", "-e", "RP_PROJECT", "reportportal/mcp-server"], "env": {"RP_API_TOKEN": "${RP_API_TOKEN}", "RP_HOST": "https://your-reportportal-instance.com", "RP_PROJECT": "YourProjectKeyFromReportPortal"}}'

For remote server:

> Note: The remote server must be deployed and running in HTTP mode before connecting.

claude mcp add-json reportportal '{"url": "http://your-mcp-server-host:port/mcp/", "headers": {"Authorization": "Bearer ${RP_API_TOKEN}", "X-Project": "YourProjectKeyFromReportPortal"}}'

Configuration Options:
- Use -s user to add the server to your user configuration (available across all projects).
- Use -s project to add the server to project-specific configuration (shared via .mcp.json).
- Default scope is local (available only to you in the current project).

Documentation: Claude Code guide.

Other Coding Agents

The ReportPortal MCP Server is compatible with any MCP-compatible coding agent. While the exact configuration format may vary, most agents support either:

Local installation (stdio mode):

{

  "reportportal": {

    "command": "docker",

    "args": ["run", "-i", "--rm", "-e", "RP_API_TOKEN", "-e", "RP_HOST", "-e", "RP_PROJECT", "reportportal/mcp-server"],

    "env": {

      "RP_API_TOKEN": "your-api-token",

      "RP_HOST": "https://your-reportportal-instance.com",

      "RP_PROJECT": "YourProjectKeyFromReportPortal"

    }

  }

}

Remote server (HTTP mode):

> Note: The remote server must be deployed and running in HTTP mode before connecting.

{
  "reportportal": {
    "url": "http://your-mcp-server-host:port/mcp/",
    "headers": {
      "Authorization": "Bearer your-api-token",
      "X-Project": "YourProjectKeyFromReportPortal"
    }
  }
}

Please refer to your coding agent's documentation for the exact configuration format and where to place the configuration file.

Once connected, your AI assistant will list ReportPortal-related "tools" it can invoke. You can then ask your questions in chat, and the assistant will call those tools on your behalf.

> Note: After completing the setup, see Verifying Your Setup section for instructions on how to test your configuration.

ReportPortal compatibility

It is strongly recommended to use the latest versions of ReportPortal.

The version 1.x of this MCP server supports ReportPortal product versions from 25.1 (where the API service version not lower than 5.14.0).\
Compatibility with older versions has not been tested and may result in incorrect work of the MCP server.

Version 2.x (currently in development) adds ReportPortal TMS tools and requires ReportPortal product version 26.1+, where the Test Case Management API is available.

Features

The ReportPortal MCP server provides a comprehensive set of capabilities for interacting with ReportPortal:

Launch Management

- Get and filter launches (test runs) with pagination - Get launch details by name or ID - Force-finish running launches - Delete launches - Run automated analysis (auto analysis, unique error analysis, quality gate) on launches - Import launches from files using ReportPortal import plugins (supported formats depend on the plugins installed on your ReportPortal instance — typically XML reports and ZIP archives, e.g. JUnit XML, Allure ZIP)

Test Item Analysis

- Get test items by launch or saved filter, with optional filters (including defect/issue type)
- Get detailed information on each test item
- View test execution statistics and failures
- Retrieve test logs and attachments
- Make a decision on test result by updating test item defect types
- Get historical execution data for test items across launches

Report Generation

- Analyze launches to get detailed test execution insights
- Generate structured reports with statistics and failure analysis

Test Case Management (TMS)

Available from MCP server version 2.x (requires ReportPortal 26.1+).

- Browse milestones, test folders, and test cases with optional filters and limit/offset pagination
- Retrieve a specific test plan by its ID
- Create and organize test folders (including nested subfolders)
- Create, update, and delete manual test cases in either supported format: text scenarios (instructions and expected results) or steps scenarios (an ordered list of steps)
- Create milestones and test plans, then assign test cases to plans
- Retrieve test cases linked to a specific test plan with optional limit/offset pagination
- List manual launches by filter (name, item status, completion state, time range, test plan, attributes) with pagination
- List test case executions for a manual launch by filter (name, priority, tags) with pagination

> Note: TMS write tools (create_, update_, delete_*, add_test_cases_to_test_plan) mutate data in ReportPortal. Use them with care in production projects.

Available Tools (commands)

Tools. Test results

| Tool Name | Description | Parameters |
|----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| Get Launches by filter | Lists ReportPortal launches with pagination by filter | name, description, owner, number, start_time, end_time, attributes, sort, page, page-size (all optional) |
| Get Last Launch by Name | Retrieves the most recent launch by name | launch (required) |
| Get Launch by ID | Retrieves a specific launch by its ID directly | project (optional, string), launch_id (required, string) |
| Run Quality Gate | Runs quality gate analysis on a launch | launch_id (required), project (optional) |
| Run Auto Analysis | Runs auto analysis on a launch | launch_id (required), analyzer_mode (optional), analyzer_type (optional), analyzer_item_modes (optional) |
| Run Unique Error Analysis | Runs unique error analysis on a launch | launch_id (required), remove_numbers (optional) |
| Update Launch | Updates the description and/or attributes of a launch | launch_id (required), description (optional, replaces existing), attributes (optional, array of {key, value} objects — replaces all existing attributes) |
| Force Finish Launch | Forces a launch to finish | launch_id (required) |
| Delete Launch | Deletes a specific launch | launch_id (required) |
| Import Launch from File | Imports a launch from a file using a ReportPortal import plugin. Supported file formats depend on the plugins installed on the server (e.g. JUnit XML, Allure ZIP). Available plugins and their accepted MIME types can be discovered via GET /api/v1/plugin (filter by groupType: "IMPORT"). The handler enforces a decoded upload limit of up to 50 MiB by default, and may apply a lower cap when the selected plugin advertises a smaller details.maxFileSize; base64-encoded uploads are measured after decoding. Imports exceeding the effective limit are rejected — split the file or pre-compress it before upload. | plugin_name (required), file_name (required, e.g. results.xml), file_content (required, raw text for text formats or base64 for binary), content_encoding (optional, "none" (default) or "base64"), project (optional) |
| Get Suites by filter | Lists test suites for a specific launch | launch-id (required), name, description, start_time_from, start_time_to, attributes, parent_id, sort, page, page-size (all optional) |
| Get Test Items by filter | Lists test items for a specific launch or saved filter | launch-id or filter-name (one required), include-before-after-hooks, name, description, status, has_retries, start_time_from, start_time_to, attributes, parent_id, defect_comment, auto_analyzed, ignored_in_aa, pattern_name, ticket_id, filter-eq-defect-type (optional defect/issue type locator from get_project_defect_types), sort, page, page-size (all optional) |
| Get Logs by filter | Lists logs for a specific test item or nested step | parent-item-id (required), log_level, log_content, logs_with_attachments, status, sort, page, page-size (all optional) |
| Get Attachment by ID | Retrieves an attachment binary by id | attachment-content-id (required) |
| Get Test Item by ID | Retrieves details of a specific test item | test_item_id (required) |
| Get Project Defect Types | Retrieves available defect types for the specific project | None |
| Update defect types by item ids | Updates defect types for multiple test items |test_items_ids (required), defect_type_id (required), defect_type_comment (optional) |
| Get Test Items History | Retrieves execution history of test items for a specific launch or parent suite | filter-eq-launchId or filter-eq-parentId (one required), historyDepth, type, name, description, status, start_time_from, start_time_to, attributes, has_retries, defect_comment, auto_analyzed, ignored_in_aa, ticket_id, pattern_name, page, page-size, page-sort (all optional) |

Tools. Test Case Management

Available from MCP server version 2.x. Requires ReportPortal 26.1+ with TMS enabled.

| Tool Name | Description | Parameters |
|----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| Get Milestones by filter | Lists TMS milestones for a project, optionally filtered by name or ID. Supports limit/offset pagination. | filter-cnt-name (optional), filter-id (optional), limit (optional, integer ≥ 1, default 50), offset (optional, integer ≥ 0, default 0) |
| Get Test Plan by ID | Retrieves a TMS test plan by its ID | id (required) |
| Get Test Cases for Test Plan | Lists test cases assigned to a TMS test plan. Supports limit/offset pagination. | test-plan-id (required), limit (optional, integer ≥ 1, default 50), offset (optional, integer ≥ 0, default 0) |
| Get Test Folders by Filter | Lists TMS test folders for a project. All filters and pagination parameters are optional. | filter-eq-id (optional, integer ≥ 1), filter-eq-parentId (optional, integer ≥ 1), filter-eq-name (optional), filter-cnt-name (optional), limit (optional, integer ≥ 1, default 50), offset (optional, integer ≥ 0, default 0) |
| Get Test Cases by Filter | Lists TMS test cases for a project. All filters and pagination parameters are optional. | filter-eq-id (optional, integer ≥ 1), filter-eq-testFolderId (optional, integer ≥ 1), filter-cnt-name (optional), filter-has-attributeKey (optional), filter-in-priority (optional, enum array: BLOCKER \| CRITICAL \| HIGH \| LOW \| MEDIUM \| UNSPECIFIED), limit (optional, integer ≥ 1, default 50), offset (optional, integer ≥ 0, default 0) |
| Create Folder | Creates a new test folder (or subfolder) in the TMS. Mutates TMS data. | name (required), description (optional), parent-test-folder-id (optional, integer ≥ 1) |
| Delete Folder | Deletes a test folder by its ID from the TMS. Mutates TMS data. Irreversible. | folderId (required, integer ≥ 1) |
| Create Test Case | Creates a new test case. Use test-case-type to choose the manual scenario. Mutates TMS data. | name (required), test-folder-id (required, integer ≥ 1 — ID of the folder to place the test case in), description (optional), priority (optional, enum: LOW \| MEDIUM \| HIGH \| CRITICAL \| BLOCKER \| UNSPECIFIED), test-case-type (optional, enum: text (default) \| steps), instructions (optional, for text type), expected-result (optional, for text type), steps (optional, array of { instructions, expected-result }, for steps type), preconditions (optional), requirements (optional, array of value strings; a unique id is generated automatically per entry), attributes (optional, array of { key } objects — tags to attach; existing project attributes matching the key are reused, missing ones are created automatically) |
| Update Test Case | Updates an existing test case; only provided fields are changed. Mutates TMS data. | testCaseId (required, integer ≥ 1), name (optional), description (optional), priority (optional, enum: LOW \| MEDIUM \| HIGH \| CRITICAL \| BLOCKER \| UNSPECIFIED), test-folder-id (optional, integer ≥ 1), test-case-type (optional, enum: text \| steps; required if any of instructions, expected-result, preconditions, requirements, or steps is provided), instructions (optional, for text type), expected-result (optional, for text type), steps (optional, array of { instructions, expected-result }, for steps type), preconditions (optional), requirements (optional, array of value strings; a unique id is generated automatically per entry), attributes (optional, array of { key } objects — tags to attach; pass [] to clear all existing tags; omit to leave unchanged) |
| Delete Test Case | Deletes a test case by its ID from the TMS. Mutates TMS data. Irreversible. | testCaseId (required, integer ≥ 1) |
| Create Milestone | Creates a new milestone in the TMS. Mutates TMS data. Dates must be RFC3339 (e.g. 2026-01-01T00:00:00Z); end-date must not precede start-date. | name (required), type (required, enum: RELEASE \| SPRINT \| PLAN \| FEATURE \| OTHER), start-date (required, RFC3339), end-date (required, RFC3339), status (optional, enum: SCHEDULED \| TESTING \| COMPLETED) |
| Create Test Plan | Creates a new test plan linked to an existing milestone. Mutates TMS data. | name (required), milestone-id (required, integer ≥ 1), description (optional) |
| Add Test Cases to Test Plan | Adds one or more test cases to an existing TMS test plan. Mutates TMS data. | test-plan-id (required, integer ≥ 1), test-case-ids (required, non-empty array of integers) |
| Get Manual Launches | Lists manual launches for a project from the TMS, filtered by name, execution status, completion state, time range, test plan, or attributes. Supports limit/offset pagination. | filter-cnt-name (optional), filter-in-itemStatus (optional, array: PASSED \| FAILED \| SKIPPED \| IN_PROGRESS), filter-eq-completion (optional, enum: has_not_executed \| done; omit for all), filter-gt-startTime (optional, RFC3339 or Unix epoch), filter-lt-endTime (optional, RFC3339 or Unix epoch), filter-eq-testPlanId (optional, integer ≥ 1), filter-has-compositeAttribute (optional, format: key1:value1,key2:value2), limit (optional, integer ≥ 1), offset (optional, integer ≥ 0) |
| Get Manual Launch Executions | Lists test case executions for a specific manual launch from the TMS. All filters and pagination parameters are optional. | launchId (required, integer ≥ 1), filter-cnt-name (optional), filter-in-priority (optional, array: BLOCKER \| CRITICAL \| HIGH \| LOW \| MEDIUM \| UNSPECIFIED), filter-in-attributeKey (optional, format: tag1,tag2,tag3), limit (optional, integer ≥ 1), offset (optional, integer ≥ 0) |

Available Prompts

Analyze Launch

Analyzes a ReportPortal launch and provides detailed information about test results, failures, and statistics.

Parameters:
- launch_id: ID of the launch to analyze

You can follow the prompt text and structure as a reference while working on your own prompts.

Example Queries (Natural Language)

Here are some real-world examples of what you might ask your AI after setup (the assistant's response will be drawn from ReportPortal data):

- "List the 5 most recent test launches." – returns a paginated list of recent test runs with names and statuses.
- "What tests failed in the latest run?" – shows failed test items for the most recent launch.
- "Show me details of launch with ID 119000." – retrieves a specific launch directly by its ID without pagination.
- "Show me details of launch with number 1234." – fetches information (ID, name, description, stats) for that specific launch.
- "Run quality gate on launch 12345." – executes quality gate analysis to verify if launch meets defined quality criteria.