Polarion MCP Server

An open-source, installable Polarion Model Context Protocol (MCP) server with write protection. It reads LiveDocs, work items, and trace relationships through the SOAP Web Services bundled with the target Polarion installation, and performs create, modify, and delete operations only after explicit confirmation.

Windows offers one-click installation and DPAPI credential encryption. Linux/macOS can be run manually with Node.js and environment variables. The repository contains no accounts, passwords, tokens, cookies, private server addresses, project IDs, or requirement bodies.

Key Capabilities

See the Functional Coverage Matrix for the full validation boundaries.

Related MCP server: permission-aware-mcp

How It Works

The MCP process does not scrape web pages, read browser cookies, or bypass Polarion permissions. Browser auto-association only hands the current Polarion tab URL to the MCP; all requirement data reads and writes are still performed entirely through SOAP MCP.

Windows One-Click Installation

Prerequisites

• Windows 10/11

• Node.js 20 or later

• Git

• Codex CLI (codex command available)

• An accessible Polarion server with /polarion/ws/services/*?wsdl exposed

• A Polarion account or PAT with the appropriate project permissions

1. Clone

git clone https://github.com/suzike/polarion-mcp-server.git
cd polarion-mcp-server

2. Install and Register

Interactive installation:

.\scripts\install.ps1

The installer will:

1. Check Node.js, npm, and Codex CLI;

2. Run npm ci, strict compilation, and tests;

3. Ask for the Polarion address and authentication method;

4. Prompt for the password or PAT in the Windows security credential prompt;

5. Back up the existing ~/.codex/config.toml;

6. Register the user-level polarion MCP;

7. Verify that Codex can read the new configuration.

Example of non-interactive configuration (credentials are still entered via the security prompt):

.\scripts\install.ps1 `
  -BaseUrl "https://polarion.example.com/polarion" `
  -DefaultProject "MY_PROJECT" `
  -DefaultDocumentLocation "Requirements/Software Requirements" `
  -AuthMode password `
  -Force

Restart Codex after installation.

3. Check the Environment

.\scripts\doctor.ps1
codex mcp get polarion

Credential Handling

Credentials never enter the repository or config.toml. The Windows installation flow writes by default:

%LOCALAPPDATA%\PolarionMcp\credentials.json

The secret is encrypted with Windows DPAPI bound to the current Windows user, and the file ACL disables inheritance and allows access only to the current user. When the MCP starts, the launcher temporarily injects the secret into the child process environment and clears it immediately on exit.

Reset credentials:

.\scripts\setup-credentials.ps1 -AuthMode password
# 或
.\scripts\setup-credentials.ps1 -AuthMode access_token

Some Polarion servers may disable PAT SOAP login. In that case, use password authentication, or contact the administrator to enable AccessToken authentication.

Usage

After restarting Codex, you can simply say:

检查 Polarion 连接状态。
读取项目 MY_PROJECT 的需求文档 Requirements/Software Requirements。
读取工作项 REQ-123，并列出它的追踪链接。
查询 MY_PROJECT 中状态为 approved 的 requirement，最多返回 20 条。

Automatic Association with the Current Browser Project

In an MCP Host that supports browser control, you can say:

读取当前浏览器打开的 Polarion 文档前 20 条需求。

The Host extracts #/project/{projectId}/... from the currently active tab URL, then passes the full URL to the tool's polarion_url parameter. The MCP validates that the URL must be same-origin with the configured Polarion service, and automatically resolves the project and wiki document location.

If the Host has no browser capability, there are multiple tabs that cannot be disambiguated, or the current tab is not Polarion, then explicitly provide project_id.

Create, Modify, and Delete

Write tools do not silently use a default project. You must explicitly pass project_id or polarion_url, and provide an exact confirmation value:

Example conversation:

在 MY_PROJECT 创建一条 task，标题为“接口检查”。执行前先给我预览并询问确认。

The Host should first present the project, type, title, and description; only after the user explicitly confirms should the confirmation string be passed. Polarion still enforces account permissions, type configuration, workflow, and audit checks.

Manual Run and Other MCP Hosts

Build:

npm ci
npm run build

Windows recommends the secure launcher:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_PROJECT_ID = "MY_PROJECT"          # 可选
$env:POLARION_NODE_PATH = (Get-Command node).Source
.\scripts\start-secure.ps1

On Linux/macOS, a password manager or process manager can provide the environment variables, then run:

export POLARION_BASE_URL="https://polarion.example.com/polarion"
export POLARION_AUTH_MODE="access_token"
export POLARION_ACCESS_TOKEN="$(your-secret-manager read polarion-token)"
node dist/index.js

Do not write the secret into a tracked .env file or MCP JSON configuration.

Update and Uninstall

Update:

git pull --ff-only
npm ci
npm test
npm run build

Unregister but keep encrypted credentials:

.\scripts\uninstall.ps1

Also delete the current Windows user's encrypted credentials:

.\scripts\uninstall.ps1 -RemoveCredentials

Validation and Development

npm test                 # 严格编译 + 单元/契约测试
npm run smoke            # MCP 协议和 8 个工具清单
npm audit --omit=dev     # 生产依赖漏洞检查

Authentication integration tests require setting non-secret target parameters yourself:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_TEST_DOCUMENT_LOCATION = "Requirements/Test Document"
$env:POLARION_TEST_WORK_ITEM_ID = "REQ-1"
npm run integration:secure

Real write self-tests refuse to run by default. Only set them after receiving explicit authorization and choosing a disposable project:

$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_CONFIRM_LIVE_WRITE_TEST = "CREATE_UPDATE_DELETE:SANDBOX_PROJECT"
npm run integration:write-self-test

This test creates a project-level temporary item, modifies it, then deletes it; it does not proactively add to a LiveDoc. Do not run write self-tests against production requirement documents.

Known Conditions and Limitations

• polarion_query_work_items requires the corresponding SOAP query permission; some accounts can read known IDs directly but cannot execute global Lucene queries.

• Work item types, statuses, and workflows vary by Polarion project; the create tool does not provide a generic default type.

• The SOAP request for creating into a LiveDoc has contract tests, but no destructive validation was performed on production documents before release.

• Current browser auto-association is orchestrated by the MCP Host, not by the MCP reading the browser directly.

• The Windows DPAPI installation script supports Windows only; other systems use environment variables or integrate with the system keychain.

Documentation

• Installation and Troubleshooting

• Architecture

• Functional Coverage Matrix

• Tool Parameter Reference

• Security Model

• Changelog

• Contributing Guide

• Security Policy

License

MIT © 2026 suzike