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

Installation

There are two ways to connect to the ReportPortal MCP Server:

Locally - via Docker (recommended) or using pre-built binaries.
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:

In Cursor, go to Settings then Tools & MCP and click Add Custom MCP.
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

Install/update the GitHub Copilot plugin.
Press Ctrl+P and type >mcp in the search bar and select MCP: Open User Configuration.
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

Install/update the GitHub Copilot plugin.
Click GitHub Copilot icon in the status bar → Edit Settings → Model Context Protocol → Configure.
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"
        }
      }
    }
  }
}

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

Open Claude Desktop, go to Settings → Developer → Edit Config.
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
    }
  }
}

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

Open your terminal.
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.
"Run an analysis on launch ABC." – triggers the ReportPortal's auto-analysis to summarize results and failures for launch "ABC".
"Finish the running launch with ID 4321." – forces a currently running test launch to stop.
"Show me the top five 500-level errors in the last hour" - lists the top 5 such errors from the recent test results.
"Import this JUnit XML report into project 'my_project' using the junit plugin." – uploads the provided report file to ReportPortal and creates a new launch from it.

Each query above corresponds to a "tool" provided by the MCP server, but you just phrase it naturally. The AI will invoke the correct command behind the scenes. These features let you query and manage your test reports in many ways through simple chat interactions.

For developers

Prerequisites

Go 1.24.4 or later
A ReportPortal instance

Building from Source

# Clone the repository
git clone https://github.com/reportportal/reportportal-mcp-server.git
cd reportportal-mcp-server

# Build the binary
go build -o reportportal-mcp-server ./cmd/reportportal-mcp-server

This creates an executable called reportportal-mcp-server.

Configuration

The server needs to know where your ReportPortal is and how to authenticate. Set these environment variables in your shell:

For stdio mode (default):

Variable	Description	Required
`RP_HOST`	The URL of your ReportPortal installation (e.g. https://myreportportal.example.com)	Yes
`RP_PROJECT`	Your default project key in ReportPortal (unique project identifier within the ReportPortal instance, e.g. `myorganization_myproject`)	No
`RP_API_TOKEN`	Your ReportPortal API token (for access)	Yes

For HTTP mode:

Set MCP_MODE=http and configure the following:

RP_HOST: Required - The URL of your ReportPortal
RP_PROJECT: Not used in HTTP mode — ignored even if set. Pass the X-Project request header per-request instead.
MCP_SERVER_PORT: Optional - HTTP server port (default: 8080)
MCP_SERVER_HOST: Optional - HTTP bind host (default: empty)
Authentication tokens must be passed per-request via Authorization: Bearer <token> header
RP_API_TOKEN environment variable is not used in HTTP mode

Example for stdio mode:

export RP_HOST="https://your-reportportal-instance.com"
export RP_PROJECT="YourProjectKeyFromReportPortal"
export RP_API_TOKEN="your-api-token"
./reportportal-mcp-server

Example for HTTP mode:

export MCP_MODE=http
export RP_HOST="https://your-reportportal-instance.com"
export MCP_SERVER_PORT=8080
./reportportal-mcp-server
# Tokens and project key are passed per-request via HTTP headers:
#   Authorization: Bearer <token>
#   X-Project: <projectKey>

HTTP API Endpoints

When running in HTTP mode (MCP_MODE=http), the server exposes the following endpoints:

MCP Endpoints (for tool calls and MCP protocol)

POST /mcp - Main MCP endpoint for JSON-RPC requests
POST /api/mcp - Alternative MCP endpoint (same functionality)
GET /mcp - SSE (Server-Sent Events) stream endpoint for MCP protocol
GET /api/mcp - Alternative SSE stream endpoint

Important: POST requests must be sent to /mcp or /api/mcp, not to the root endpoint /.

Request Format:

All MCP requests must follow the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_launches",
    "arguments": {
      "filter-cnt-name": "test",
      "page": 1,
      "page-size": 10
    }
  }
}

Example Request:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-reportportal-token" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
      "name": "get_launches",
      "arguments": {
        "page": 1,
        "page-size": 10
      }
    }
  }'

Information Endpoints (GET only)

GET / - Root endpoint, returns server information and available endpoints
GET /health - Health check endpoint
GET /info - Server information and configuration
GET /api/status - Server status (same as /info)
GET /metrics - Analytics metrics (if analytics enabled)

Note: The root endpoint / only accepts GET requests. POST requests to / will return a 404 error. Use /mcp or /api/mcp for MCP protocol requests.

Starting the Server

The server will start in the mode specified by MCP_MODE environment variable (default: stdio).

Once running, the MCP server is ready to accept queries from your AI tool.

Development

To set up a development environment or contribute:

Task Tool

Install Go Task v3:

go install github.com/go-task/task/v3/cmd/task@latest

Dependencies

Run task deps to install Go dependencies:

task deps

Build

task build

Tests

task test

Build with Docker

task docker:build

Debugging with MCP Inspector

The modelcontextprotocol/inspector tool is useful for testing and debugging MCP servers locally:

npx @modelcontextprotocol/inspector docker run -i --rm -e "RP_API_TOKEN=$RP_API_TOKEN" -e "RP_PROJECT=$RP_PROJECT" -e "RP_HOST=$RP_HOST" reportportal-mcp-server

Alternatively, you can use the Task command:

# Run inspector against your local server
task inspector

Code Quality

# Lint
task lint

# Format
task fmt

Extending the Server

Adding new Tools

To add a new tool, create a new method in the appropriate resource file and add it to the server in the NewServer function:

// In your resource file (e.g., launches.go)
func (lr *LaunchResources) toolNewFeature() (tool mcp.Tool, handler server.ToolHandlerFunc) {
    // Implement your tool
}

// In server.go
func NewServer(...) *server.MCPServer {
    // ...
    s.AddTool(launches.toolNewFeature())
    // ...
}

Adding new Prompts

To add a new prompt, simply create a YAML file describing your prompt and place it in the prompts folder at the root of the project. The server will automatically read and initialize all prompts from this directory on startup—no code changes are required.

Example:

Use an existing or create a new file, e.g., my_custom_prompt.yaml, in the prompts folder.
Define your prompt logic and parameters in YAML format.
Rebuild the server to load the new prompt.

This approach allows you to extend the server's capabilities with custom prompts quickly and without modifying the codebase.

Verifying Your Setup

1. Verify ReportPortal Accessibility

Before testing the MCP server, ensure your ReportPortal instance is accessible:

Via Browser:

Open your ReportPortal URL (RP_HOST) in a web browser
You should see the ReportPortal login page or dashboard
Verify you can log in with your credentials

Via Command Line (curl):

# Test basic connectivity
curl -I https://your-reportportal-instance.com

# Test API access with your token
curl -H "Authorization: Bearer your-api-token" \
     https://your-reportportal-instance.com/api/v1/YourProjectKey/launch

Via PowerShell:

# Test basic connectivity
Invoke-WebRequest -Uri "https://your-reportportal-instance.com" -Method Head

# Test API access
$headers = @{
    "Authorization" = "Bearer your-api-token"
}
Invoke-RestMethod -Uri "https://your-reportportal-instance.com/api/v1/YourProjectKey/launch" -Headers $headers

Expected Results:

HTTP 200 OK response
Valid JSON response with launch data (if project has launches)
No authentication errors (401) or forbidden errors (403)

2. Verify Remote MCP Server (if using remote deployment)

If connecting to a remote MCP server, verify it's accessible:

Via Browser:

http://your-mcp-server-host:port/

Should return server information and available endpoints.

Via curl (GET request):

# Check server health
curl http://your-mcp-server-host:port/health

# Check server info
curl http://your-mcp-server-host:port/info

Via curl (MCP protocol test):

# Test MCP endpoint with JSON-RPC request
curl -X POST http://your-mcp-server-host:port/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -H "X-Project: YourProjectKey" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Via PowerShell:

# Check server health
Invoke-RestMethod -Uri "http://your-mcp-server-host:port/health"

# Test MCP endpoint
$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer your-api-token"
    "X-Project" = "YourProjectKey"
}
$body = @{
    jsonrpc = "2.0"
    method = "tools/list"
    id = 1
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://your-mcp-server-host:port/mcp" -Method Post -Headers $headers -Body $body

Via ping (network connectivity only):

ping your-mcp-server-host

Expected Results:

Server responds to health checks
/info returns server configuration
MCP endpoint returns list of available tools
No connection refused or timeout errors

3. Verify MCP Server Integration

After configuration, verify the AI assistant can communicate with the MCP server:

Step 1: Check Available Tools

Ask your AI assistant:

"What ReportPortal tools are available?"

Expected response: A list of 33 tools including launches, test items, analysis tools, TMS tools, etc.

Step 2: Test Basic Query

Try a simple query:

"List the 5 most recent test launches"

Expected response: A formatted list of recent launches with names, statuses, and timestamps.

Step 3: Check Server Logs

Monitor logs to verify requests are being processed:

Docker:

# View logs
docker logs <container-name>

# Follow logs in real-time
docker logs -f <container-name>

# View last 50 lines
docker logs --tail 50 <container-name>

Binary (stdio mode): Check the terminal output where the server is running. You should see log entries for each request.

Binary (HTTP mode):

# If redirecting to file
./reportportal-mcp-server > server.log 2>&1

# Then view logs
tail -f server.log

Expected Log Output:

INFO: MCP server started
INFO: Received request: tools/list
INFO: Processing tool call: get_launches
DEBUG: Calling ReportPortal API: /api/v1/projectKey/launch

4. Common Verification Issues

Issue	Cause	Solution
AI shows no ReportPortal tools	MCP server not connected	Check configuration file syntax, restart AI assistant
"Connection refused" error	Server not running or wrong port	Verify server is running: `docker ps` or check process
"401 Unauthorized"	Invalid API token	Regenerate token in ReportPortal profile
"403 Forbidden"	Token valid but no project access	Check `RP_PROJECT` key (must match the `Project KEY`, not the display name), verify user has access
"404 Not Found"	Wrong endpoint URL	Ensure remote URL ends with `/mcp/`
Empty results from queries	No data in ReportPortal	Run some tests first to populate data
Timeout errors	Network issues or slow ReportPortal	Check network connectivity, ReportPortal performance

Troubleshooting

Connection Issues

Problem: Cannot connect to ReportPortal

Symptoms:

"Connection refused" errors
"Could not resolve host" errors
Timeout errors

Solutions:

Verify RP_HOST is correct and includes protocol (https:// or http://)
Check network connectivity: ping your-reportportal-host
Verify ReportPortal is running and accessible
Check firewall rules allow connection to ReportPortal
For HTTPS, verify SSL certificates are valid

Problem: Cannot connect to remote MCP server

Symptoms:

"Connection refused" on MCP server
"No route to host" errors

Solutions:

Verify MCP server is running: Check with curl http://host:port/health
Check MCP_MODE=http is set on the server
Verify port is correct (default: 8080)
Check firewall/security groups allow access to the port
Ensure server is bound to correct network interface (MCP_SERVER_HOST)

Authentication Issues

Problem: 401 Unauthorized errors

Solutions:

Verify API token is correct and not expired
Regenerate token in ReportPortal: Profile → API Keys → Generate New Token
Check token is properly set in environment variable or configuration
For remote servers, verify Authorization: Bearer <token> header is sent
Ensure no extra spaces or quotes around the token value

Problem: 403 Forbidden errors

Solutions:

Verify user has access to the specified project
Check project key (RP_PROJECT) matches exactly (case-sensitive, must be the Project Key, not the display name)
Verify user role has sufficient permissions
For remote servers, check X-Project header is set correctly

Docker Issues

Problem: Docker container exits immediately

Solutions:

Check container logs: docker logs <container-name>
Verify all required environment variables are set
Ensure environment variable values don't have syntax errors
Check Docker has permission to access the network

Problem: "docker: command not found"

Solutions:

Install Docker Desktop for your OS
Verify Docker is running: docker --version
For Linux, add user to docker group: sudo usermod -aG docker $USER

AI Assistant Integration Issues

Problem: AI assistant doesn't recognize MCP server

Solutions:

Verify configuration file syntax is valid JSON
Check configuration file is in the correct location
Restart the AI assistant after configuration changes
For Cursor/VS Code, check MCP extension is installed and enabled
Review AI assistant logs for error messages

Problem: Tools list is empty

Solutions:

Verify MCP server is running and accessible
Check server logs for startup errors
Ensure server mode matches client configuration (stdio vs HTTP)
For remote servers, verify URL ends with /mcp/

Performance Issues

Problem: Slow responses or timeouts

Solutions:

Check ReportPortal API performance (test with curl)
Reduce page size in queries (page-size parameter)
Use filters to limit data retrieval
Check network latency between server and ReportPortal
Monitor server resources (CPU, memory)

Problem: High memory usage

Solutions:

Reduce concurrent requests
Limit result set sizes with pagination
Restart the MCP server periodically
Check for memory leaks in logs

Configuration Issues

Problem: "Environment variable not set"

Solutions:

Verify variable names are correct: RP_HOST, RP_PROJECT, RP_API_TOKEN
For Docker, check -e flags are specified correctly
For binary, export variables in the same shell session
Use echo $VAR_NAME (Linux/Mac) or $env:VAR_NAME (PowerShell) to verify

Problem: "Invalid JSON" configuration errors

Solutions:

Validate JSON syntax using a JSON validator
Remove trailing commas in JSON objects
Ensure all strings are properly quoted
Check for comments (JSON doesn't support comments)
Verify escape characters in paths (use \\ in Windows paths)

Getting Help

If you're still experiencing issues:

Check Logs: Enable debug logging and review detailed error messages
Test Components: Verify each component separately (ReportPortal → MCP Server → AI Assistant)
GitHub Issues: Search or create an issue at reportportal-mcp-server
Documentation: Review MCP specification and ReportPortal API docs
Community: Join ReportPortal community for support

License

This project is licensed under the Apache 2.0 License.

Name		Name	Last commit message	Last commit date
Latest commit History 140 Commits
.github/workflows		.github/workflows
cmd		cmd
helm-charts/reportportal-mcp-server		helm-charts/reportportal-mcp-server
internal		internal
.coderabbit.yaml		.coderabbit.yaml
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
Taskfile.yaml		Taskfile.yaml
debug.dockerfile		debug.dockerfile
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum
release.dockerfile		release.dockerfile

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ReportPortal MCP Server

What is the ReportPortal MCP Server?

Why Use It?

Prerequisites

ReportPortal Host URL (RP_HOST)

Project Key (RP_PROJECT) — Optional

API Token (RP_API_TOKEN)

Server Mode (MCP_MODE)

Installation

Local installation

Via Docker (recommended)

Using pre-built binaries

Connecting to a Remote MCP Server

AI Tool Setup

Cursor (AI Code Editor)

GitHub Copilot (In VS Code and JetBrains IDEs)

VS Code

JetBrains IDEs

Claude Desktop

Claude Code CLI

Other Coding Agents

ReportPortal compatibility

Features

Launch Management

Test Item Analysis

Report Generation

Test Case Management (TMS)

Available Tools (commands)

Tools. Test results

Tools. Test Case Management

Available Prompts

Analyze Launch

Example Queries (Natural Language)

For developers

Prerequisites

Building from Source

Configuration

HTTP API Endpoints

MCP Endpoints (for tool calls and MCP protocol)

Information Endpoints (GET only)

Starting the Server

Development

Task Tool

Dependencies

Build

Tests

Build with Docker

Debugging with MCP Inspector

Code Quality

Extending the Server

Adding new Tools

Adding new Prompts

Verifying Your Setup

1. Verify ReportPortal Accessibility

2. Verify Remote MCP Server (if using remote deployment)

3. Verify MCP Server Integration

4. Common Verification Issues

Troubleshooting

Connection Issues

Authentication Issues

Docker Issues

AI Assistant Integration Issues

Performance Issues

Configuration Issues

Getting Help

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

ReportPortal Host URL (`RP_HOST`)

Project Key (`RP_PROJECT`) — Optional

API Token (`RP_API_TOKEN`)

Server Mode (`MCP_MODE`)

Packages