Which integrations are available for this server?

Offers a REST API for OpenAI GPT Actions to interact with Polarion, enabling querying and managing Polarion entities via HTTP.

How do I use PolarionMcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PolarionMcp search for open defects in myproject" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-polarion

A CLI-first Polarion ALM client with MCP server support for AI assistants (Cline, Claude Code, Copilot Studio) and a REST API for OpenAI GPT Actions and other HTTP consumers.

Installation

git clone https://github.com/mmerah/PolarionMcp.git
cd PolarionMcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Create a .env file:

POLARION_URL=https://your-polarion-instance.com/polarion
POLARION_USER=your-username
POLARION_TOKEN=your-personal-access-token

CLI Usage

# Connection
mcp-polarion health

# Projects
mcp-polarion projects                       # list all configured aliases
mcp-polarion project -p myproject           # name & description
mcp-polarion project-types -p myproject     # configured work item types + fields
mcp-polarion named-queries -p myproject     # named queries defined in config
mcp-polarion discover-types -p myproject    # sample the project to find types
mcp-polarion discover-types -p myproject --limit 500

# Work items
mcp-polarion get ADC-1234                   # project inferred from ID prefix
mcp-polarion get ADC-1234 -p myproject
mcp-polarion search "type:defect AND status:open" -p myproject
mcp-polarion search "query:open_bugs" -p myproject  # named query
mcp-polarion search "type:defect" -p myproject --fields "id,title,status"

# Tests & documents
mcp-polarion test-runs -p myproject
mcp-polarion test-run TR-42 -p myproject
mcp-polarion documents -p myproject
mcp-polarion test-specs QA/TestSpecs -p myproject

# Plans (plan projects only)
mcp-polarion plans -p releases
mcp-polarion plan R2024.4 -p releases
mcp-polarion plan-workitems R2024.4 -p releases
mcp-polarion search-plans "templateId:release" -p releases

# Servers
mcp-polarion serve                          # HTTP works for all clients
mcp-polarion serve --mode stdio             # stdio transport for local .mcp.json
mcp-polarion serve --port 9000 --log-level DEBUG

# Utilities. Output goes to generated/
mcp-polarion docgen                         # generated/agent_instructions*.md
mcp-polarion generate-openapi               # generated/openapi.yaml
mcp-polarion import-custom-fields --path local/custom-fields/myproject

The convenience script run_server.sh handles first-time venv setup and .env checks before calling mcp-polarion serve.

Configuration

The optional local config unlocks project aliases, named queries, custom field mappings, and plan project support. The tracked example lives in local/. Copy it to get started:

cp local/polarion_config.example.yaml local/polarion_config.yaml

projects:
  myproject:                          # alias (use this everywhere)
    id: ACTUAL_PROJECT_ID             # real Polarion project ID
    work_item_types:
      - systemRequirement
      - defect
    custom_fields:
      defect: [severity, foundIn]
      systemRequirement: [acceptanceCriteria, riskRelevance]
    default_queries:
      open_bugs: "type:defect AND status:open"
      my_items: "assignee.id:$current_user"

  releases:
    id: RELEASES_PROJECT
    is_plan: true                     # enables plan-specific tools

display_fields: [id, title, type, status, assignee]

After editing the config, regenerate the agent instructions and OpenAPI spec:

mcp-polarion docgen                         # generated/agent_instructions*.md
mcp-polarion generate-openapi               # generated/openapi.yaml

For custom field imports, keep downloaded XML exports local and untracked:

local/custom-fields/<project-alias>/
  requirement-custom-fields.xml
  defect-custom-fields.xml

Usually, those custom-fields.yml are located in a Polarion project administration content. They can be downloaded from there. Then import them with:

mcp-polarion import-custom-fields --path local/custom-fields/myproject

See docs/XML_PARSER.md for the full import workflow.

Available Tools

See docs/WORKFLOW_EXAMPLES.md for tool usage patterns.

General

Tool	Description
`health_check`	Check Polarion connectivity
`get_project_info`	Project name and description
`list_projects`	All configured project aliases
`get_project_types`	Configured work item types for a project
`get_named_queries`	Named queries defined for a project
`discover_work_item_types`	Sample a project to find its work item types

Work Items (regular projects)

Tool	Description
`get_workitem`	Full details for one or more work items, including custom fields and test steps
`search_workitems`	Lucene query search; accepts named queries (`query:open_bugs`), optional `field_list`, and optional `limit`

Test & Documents

Tool	Description
`get_test_runs`	List all test runs
`get_test_run`	Details of one test run
`get_documents`	List documents in a project, with optional `limit` and document paths
`get_document`	Export a document PDF to `/tmp` and return local path plus artifact download info
`get_test_specs_from_document`	Extract test spec IDs from a document

Plans (plan projects only)

Tool	Description
`get_plans`	List all plans (releases, iterations)
`get_plan`	Details of one plan
`get_plan_workitems`	Work items in a plan
`search_plans`	Lucene search across plans

Inputs: project_alias accepts both aliases (myproject) and real IDs (ACTUAL_PROJECT_ID).
Outputs: Human-readable strings. Errors start with ❌.

MCP Server Integration

A single mcp-polarion serve command serves all HTTP clients. The server uses stateless requests (one session per POST) and JSON responses, which enables parallel tool calls and works equally well with Cline, Claude Code, Copilot Studio, and GPT Actions (via the REST API).

Cline / Claude Code (HTTP)

mcp-polarion serve          # http://0.0.0.0:8000/mcp

Add to Cline's MCP settings:

{
  "mcpServers": {
    "polarion": { "url": "http://localhost:8000/mcp" }
  }
}

Claude Code / `.mcp.json` (stdio)

{
  "mcpServers": {
    "polarion": {
      "command": "mcp-polarion",
      "args": ["serve", "--mode", "stdio"]
    }
  }
}

Microsoft Copilot Studio

mcp-polarion serve

Expose over HTTPS (e.g. Azure Dev Tunnel), then follow the MCP onboarding wizard: Add a tool → New tool → Model Context Protocol. Use https://<your-host>/mcp as the server URL.

REST API / GPT Actions (OpenAI)

mcp-polarion serve

REST endpoints are available at /actions/ alongside the MCP endpoint. Generate the OpenAPI spec and agent instructions first:

mcp-polarion generate-openapi               # generated/openapi.yaml
mcp-polarion docgen                         # generated/agent_instructions*.md

The running server also serves the spec at /openapi.json and /openapi.yaml.

curl http://localhost:8000/actions/projects
curl http://localhost:8000/openapi.json | jq '.paths | keys'

Use generated/agent_instructions.md as a knowledge file and generated/agent_instructions_simple.md as the system prompt for your custom GPT.

Project Structure

polarion_mcp/
  core/           Polarion domain logic: client, config, settings, formatters
  config/         Config discovery and XML import utilities
  mcp/            MCP layer: tool definitions, middleware, server, stdio
  rest_api/       REST API routes and OpenAPI spec generation
  docgen/         Agent instruction doc generator
  cli/            CLI entry point (mcp-polarion)
docs/             Supporting guides and workflow references
local/            Workspace-local config and XML exports
generated/        Generated files (openapi.yaml, agent_instructions)
tests/
run_server.sh              First-time bootstrapper (venv + deps + serve)

Shell Completion

Basic tab completion for subcommands and flags is available via argcomplete. After reinstalling the package, enable it in your shell:

pip install -e .
eval "$(register-python-argcomplete mcp-polarion)"

For bash, add that line to ~/.bashrc. For zsh, enable bash completion compatibility first, then register the same command.

Development

pytest
black polarion_mcp tests
isort polarion_mcp tests
mypy polarion_mcp

License

MIT. See LICENSE.

PolarionMcp

mcp-polarion

Installation

CLI Usage

Configuration

Available Tools

General

Work Items (regular projects)

Test & Documents

Plans (plan projects only)

MCP Server Integration

Cline / Claude Code (HTTP)

Claude Code / `.mcp.json` (stdio)

Microsoft Copilot Studio

REST API / GPT Actions (OpenAI)

Project Structure

Shell Completion

Development

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

mcp-polarion

Installation

CLI Usage

Configuration

Available Tools

General

Work Items (regular projects)

Test & Documents

Plans (plan projects only)

MCP Server Integration

Cline / Claude Code (HTTP)

Claude Code / .mcp.json (stdio)

Microsoft Copilot Studio

REST API / GPT Actions (OpenAI)

Project Structure

Shell Completion

Development

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

Claude Code / `.mcp.json` (stdio)