Polarion MCP Servers

This repository contains Model Context Protocol (MCP) server implementations for Polarion Application Lifecycle Management (ALM) integration.

MCP Tools are available for Polarion work items, including:

• get_text_for_workitems_by_id: Gets the main text content for specified WorkItem IDs.
• get_text_for_workitem_at_revision: Gets the text content for a single WorkItem at a specific revision.
• get_details_for_workitems: Gets detailed information for specified WorkItem IDs including status, type, assignee, custom fields, and linked work items.
• get_documents: Lists documents in the project, optionally filtered by title.
• get_documents_by_space_names: Lists documents within specified space names.
• get_space_names: Lists all available space names in the project.
• get_sections_in_document: Gets the list of sections in a document.
• get_section_content_for_document: Gets the content of a specific section in a document.
• search_workitems_in_document: Searches for WorkItems within a document based on text criteria.
• list_available_custom_fields_for_workitem_types: Lists all available custom fields for specific WorkItem types.
• list_available_workitem_types: Lists all WorkItem types available in the project.
• get_revisions_list_for_workitem: Gets the list of revision IDs for a specific work item, ordered from newest to oldest.
• get_revisions_content_for_workitem: Gets the content of a work item at different revisions, including title, status, description, and other standard fields.

Projects

• PolarionRemoteMcpServer: (Streamable HTTP or SSE) based MCP server for server based installations
• PolarionMcpServer: Console-based MCP server for Polarion integration for local workstation installations

Running via Docker & Linux Server (Recommended)

1. From your Linux server, create a directory for your configuration and logs:

   mkdir -p /opt/polarion-mcp-server
   cd /opt/polarion-mcp-server

2. Pull the Docker image:

   docker pull peakflames/polarion-remote-mcp-server

3. Create a tailored /opt/polarion-mcp-server/appsettings.json file to your Polarion configuration:

   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft.AspNetCore": "Warning"
       }
     },
     "AllowedHosts": "*",
     "ApiConsumers": {
       "Consumers": {
         "my_app": {
           "Name": "My Application",
           "ApplicationKey": "your-secure-api-key-here",
           "Active": true,
           "AllowedScopes": ["polarion:read"],
           "Description": "API consumer for my application"
         }
       }
     },
     "PolarionProjects": [
          {
              "ProjectUrlAlias": "starlight", 
              "Default": true,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "shared_user_read_only",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "Starlight_Main", 
                  "TimeoutSeconds": 60
              },
              "PolarionWorkItemTypes": [
                {
                  "id": "requirement",
                  "fields": ["custom_field_1", "priority", "severity"]
                },
                {
                  "id": "defect",
                  "fields": ["defect_type", "found_in_build"]
                }
              ]
          },
          {
              "ProjectUrlAlias": "octopus", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion.int.mycompany.com/",
                  "Username": "some_other_user",
                  "Password": "linear-Vietnam-FLIP-212824", 
                  "ProjectId": "octopus_gov", 
                  "TimeoutSeconds": 60
              }
          },
          {
              "ProjectUrlAlias": "grogu", 
              "Default": false,
              "SessionConfig": { 
                  "ServerUrl": "https://polarion-dev.int.mycompany.com/",
                  "Username": "vader",
                  "Password": "12345", 
                  "ProjectId": "grogu_boss", 
                  "TimeoutSeconds": 60
              }
          }
      ]
   }

4. Run the Docker container:

   docker run -d \
     --name polarion-mcp-server \
     -p 8080:8080 \
     -v appsettings.json:/app/appsettings.json \
     peakflames/polarion-remote-mcp-server

5. The server should now be running. MCP clients will connect using a URL specific to the desired project configuration alias:

   1. Streamable HTTP Transport: http://{{your-server-ip}}:8080/{ProjectUrlAlias}.
   2. SSE Transport: http://{{your-server-ip}}:8080/{ProjectUrlAlias}/sse.

6. The server also provides:

   • REST API: http://{{your-server-ip}}:8080/polarion/rest/v1/projects/{ProjectId}/... (uses SessionConfig.ProjectId)
     • Note: REST API endpoints require API key authentication via X-API-Key header
   • API Documentation: http://{{your-server-ip}}:8080/scalar/v1 (includes authentication UI)
   • Health Check: http://{{your-server-ip}}:8080/api/health

7. 📢IMPORTANT - Do NOT run with replica instances of the server as the session connection will not be shared between replicas.

Configuration Options

Configuration Files:

• appsettings.json - Base configuration for production/server deployments
• appsettings.Development.json - Overrides base settings for local development (gitignored, takes precedence in Development mode)
• .env - Optional environment variables (copy from .env.example), can set POLARION_DEFAULT_PROJECT

The server uses a PolarionProjects array in appsettings.json to define one or more Polarion instance configurations. Each object in the array represents a distinct configuration accessible via a unique URL alias.

Top-Level Setting	Description
PolarionProjects	(Array) Contains one or more Polarion project configuration objects.

Each Project Configuration Object:

Setting	Description	Required	Default
ProjectUrlAlias	A unique string used in the connection URL (/{ProjectUrlAlias}/sse) to identify this configuration.	Yes	N/A
Default	(boolean) If true, this configuration is used if the client connects without specifying a ProjectUrlAlias. Only one entry can be true.	No	false
SessionConfig	(Object) Contains the specific connection details for this Polarion instance.	Yes	N/A
PolarionWorkItemTypes	(Array, Optional) Defines custom fields to retrieve for specific WorkItem types within this project. Each object in the array should have an id (string, WorkItem type ID) and fields (array of strings, custom field names).	No	Empty List

SessionConfig Object Details:

Setting	Description	Required	Default
ServerUrl	URL of the Polarion server (e.g., "https://polarion.example.com/")	Yes	N/A
Username	Polarion username with appropriate permissions.	Yes	N/A
Password	Password for the Polarion user. (Consider secure alternatives)	Yes	N/A
ProjectId	The actual ID of the Polarion project to interact with.	Yes	N/A
TimeoutSeconds	Connection timeout in seconds.	No	60

Environment Variable Password Override

Instead of placing passwords in configuration files, set the POLARION_PASSWORD environment variable. When set, it overrides SessionConfig.Password for all configured projects.

Docker example:

docker run -d \
  --name polarion-mcp-server \
  -p 8080:8080 \
  -e POLARION_PASSWORD=your-secret-password \
  -v appsettings.json:/app/appsettings.json \
  peakflames/polarion-remote-mcp-server

This works for both PolarionRemoteMcpServer (HTTP) and PolarionMcpServer (stdio).

Note: It is strongly recommended to use the POLARION_PASSWORD environment variable or more secure methods for storing credentials (like User Secrets, Azure Key Vault, etc.) rather than placing plain text passwords in appsettings.json.

REST API Specification Alignment

The REST API is designed to align with the official Polarion REST API specification available at https://testdrive.polarion.com/polarion/rest/v1/definition. A local copy of this definition is maintained at docs/polarion-rest-vq-definition.json for reference when implementing or extending endpoints.

API Key Authentication (REST API Only)

REST API endpoints require authentication via API key. Configure API consumers in the ApiConsumers section of appsettings.json:

Setting	Description	Required
ApiConsumers.Consumers	Dictionary of consumer configurations keyed by consumer ID	Yes
Name	Display name for the API consumer	Yes
ApplicationKey	The API key used for authentication	Yes
Active	Whether the consumer is allowed to authenticate	Yes
AllowedScopes	List of scopes (e.g., ["polarion:read"])	Yes
Description	Optional description of the consumer	No

Available Scopes:

• polarion:read - Read access to all REST API endpoints

Usage:

curl -H "X-API-Key: your-api-key" http://localhost:8080/polarion/rest/v1/projects/{projectId}/spaces

Note: MCP endpoints, health checks (/api/health, /api/version), and API documentation (/scalar/v1) do not require authentication.

Configuring MCP Clients

To configure Cline:

1. Open Cline's MCP settings UI
2. Click the "Remote Servers" tab
3. For each ProjectUrlAlias in your appsettings.json that the user wants to connect to:

{
  "mcpServers": {
    ...
    ...

    "Polarion Starling": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/starlight/sse",
      "transportType": "sse"
    },
    "Polarion Octopus": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/octopus/sse",
    "transportType": "sse"
    }
  ...
  ...
}

1. Repeat for each ProjectUrlAlias you want to connect to.

To configure Visual Studio Code:

Add the following configuration to your settings.json file:

"servers": {
    "polarion-starlight": { // Use a descriptive key
        "type": "sse",
        "url": "http://{{your-server-ip}}:8080/starlight/sse", // Replace with your alias
        "env": {}
    },
    "polarion-octopus": { 
        "type": "sse",
        "url": "http://{{your-server-ip}}:8080/octopus/sse", // Replace with your alias
        "env": {}
    }
    // Add entries for each ProjectUrlAlias
}

To Claude Desktop:

Claude Desktop currently doesn’t support SSE, but you can use a proxy with the following addition to the claude_desktop_config.json file:

{
  "mcpServers": {
    "polarion-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://{{your-server-ip}}:8080/{ProjectUrlAlias}/sse" // Replace {ProjectUrlAlias}
      ]
    }
    // Add entries for each ProjectUrlAlias, potentially using different keys like "polarion-starlight"
  }
}

Running Locally (stdio)

For local development or workstation use, you can run the stdio-based MCP server:

1. Download the appropriate executable for your platform from the releases page
2. Configure your MCP client to use the stdio transport with the executable path

Contributing

For developers who want to contribute or build from source, see CONTRIBUTING.md.

License

See LICENSE for details.