ReportPortal MCP Server for Natural Language Queries

Overview

The ReportPortal MCP Server is a lightweight adapter that exposes ReportPortal data to MCP-compatible AI assistants and tools. It implements the Model Context Protocol (MCP) to let chat-based AI clients query test runs, failures, trends and other ReportPortal entities using plain-English prompts. Instead of opening the ReportPortal UI or writing API scripts, you can ask an assistant questions like “What failed in the last nightly run?” and receive structured, human-friendly answers sourced from your ReportPortal instance.

The server supports two transport modes: a local stdio mode optimized for desktop AI integrations (Claude Desktop, Cursor, VS Code Copilot, etc.), and an HTTP/SSE mode for centrally hosted deployments that multiple clients can call. Authentication to ReportPortal is performed using your API token; the server forwards queries to ReportPortal, translates results to MCP-compatible responses, and streams updates back to the client when relevant.

Features

• Natural-language access to ReportPortal test data via MCP-compliant responses
• Supports stdio mode for local AI tool integrations and HTTP/SSE for remote clients
• Built-in handlers for common queries: list runs, failures, error details, aggregates
• Minimal deployment footprint — run as a Docker container or a native binary
• Works with any AI tool that understands the MCP spec
• Optionally set a default project to simplify queries

Installation / Configuration

You can run the MCP server locally (recommended for personal AI integrations) or deploy it in HTTP mode for shared usage.

Required environment variables (common):

Docker (recommended)

docker run -i --rm \
  -e RP_API_TOKEN="your-api-token" \
  -e RP_HOST="https://your-reportportal.example.com" \
  -e RP_PROJECT="MyProject" \
  reportportal/mcp-server

This runs the server in stdio mode by default. To run the HTTP server, add MCP_MODE=http:

docker run -i --rm \
  -e RP_API_TOKEN="your-api-token" \
  -e RP_HOST="https://your-reportportal.example.com" \
  -e MCP_MODE="http" \
  -p 8080:8080 \
  reportportal/mcp-server

Pre-built binary

# stdio mode (default)
./reportportal-mcp-server stdio

# http mode
MCP_MODE=http ./reportportal-mcp-server

Remote/HTTP client configuration If the server is deployed with MCP_MODE=http, AI tools can call its MCP endpoint. Typical client headers:

{
  "Authorization": "Bearer <MCP-server-token-or-proxy>",
  "X-Project": "MyProject"
}

(How you secure the exposed HTTP endpoint depends on your environment — use TLS, API gateways or network restrictions.)

Security note: never commit RP_API_TOKEN or other secrets to source control. Store them in environment variables or secret stores.

Available Resources

• GitHub repository: https://github.com/reportportal/reportportal-mcp-server
• MCP specification and overview: https://modelcontextprotocol.io/overview
• Releases (binaries & images): see the repository Releases page
• ReportPortal API docs: use your instance’s API reference for advanced queries

How it works (brief)

1. The AI client sends an MCP request (via stdio or HTTP) describing the user’s natural-language query.
2. The MCP server receives the request and maps it to ReportPortal API calls (using RP_HOST and RP_API_TOKEN).
3. Results from ReportPortal are formatted into the MCP response structure and sent back to the client. For long-running queries, the server can stream partial results using SSE when in HTTP mode.

Use Cases

• Quick failure triage

  • Prompt: “Which tests failed in the latest run and why?”
  • Result: List of failed tests with failure messages, stack traces pointers, and links to the run in ReportPortal.

• Recent runs summary

  • Prompt: “List the five most recent test runs for project MyProject.”
  • Result: A compact table of run names, start times, duration, and pass/fail counts.

• Flakiness and trends

  • Prompt: “Show the top 5 most flaky tests in the last 30 days.”
  • Result: Ranked list of tests with flakiness score, failure rate, and recent occurrences.

• Regression detection

  • Prompt: “Did any test regress compared to the last successful run?”
  • Result: Diff-style summary highlighting tests that started failing and when they last passed.

Example assistant workflow:

1. User asks a question in their AI assistant.
2. The assistant sends an MCP request to this server.
3. The server queries ReportPortal and returns an answer that the assistant displays to the user.

Getting started tips

• For personal use with a desktop AI client, run the server locally in stdio mode and configure your AI tool to use the local process.
• For team/shared access, deploy with MCP_MODE=http behind HTTPS and restrict access via firewall or API gateway.
• Start by setting RP_PROJECT if most queries target a single project — it reduces the need to pass project identifiers in each request.

This server is intended as a bridge that simplifies querying ReportPortal through natural language. Refer to the repository and MCP spec for advanced integration details and example prompts.