Polarion MCP
This MCP server enables AI assistants to read and write Polarion ALM data via the Polarion REST API.
Discovery & Reading
List projects – Browse accessible Polarion projects
List documents – Discover documents within a project
Get document details – Retrieve metadata, raw HTML body, or render as flowing Markdown
List document parts – Inspect headings, work items, and prose blocks with embedded metadata
Search work items – Find work items using Lucene or SQL queries (module-scoped, custom fields, traceability)
Get work item details – Full details with raw HTML or Markdown-rendered description
List links – View outgoing/incoming traceability links with roles, suspect flags, and linked item metadata
List comments – Retrieve document comments with thread relationships
Resolve enum options – Get valid values for document and work item fields (status, type, severity, priority, custom enums)
Writing
Create/update work items – Create free-floating work items or patch title, status, description, priority, severity, assignees, custom fields, hyperlinks, and workflow actions
Create/update documents – Create new documents with optional Markdown body, or patch metadata, body HTML, and workflow actions
Manage links – Create, update (suspect flag, revision), or delete outgoing work item links in bulk
Move work items – Attach a work item into a document at a specific position, or detach it back to free-floating
Manage comments – Create top-level comments or replies, and resolve or re-open them
Most write operations support a dry_run mode that previews the JSON:API payload without making changes.
Enables GitHub Copilot to interact with Polarion ALM, allowing AI assistants to read, create, update, and reorganize work items, documents, and traceability links.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Polarion MCP list work items in project 'MyProject' where status is 'open'"
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-server-polarion
Talk to your Polarion — AI reads, writes, and reorganizes documents, work items, test runs, and traceability links.
Features · Quickstart · Tools · Example Prompts · Setup
A Model Context Protocol (MCP) server for Polarion ALM, built for real-world instances: every write supports dry_run, guards validate fields and enum values before anything is committed, and requests are paced to a rate cap you configure for your instance — so an AI assistant can work on production data without surprises.

Features
46 tools covering read and write across documents, work items, test runs, traceability links, comments, and attachments.
Read — render documents as Markdown, search with Lucene or SQL, walk incoming/outgoing links, resolve enum options.
Write — create and update work items, documents, and test runs, manage links, reorganize document structure, post comments.
Safe writes — every write tool supports
dry_run, and pre-write guards validate fields, enum values, and link targets before hitting Polarion.Plays nice with your server — requests are serialized and paced to a configurable rate cap, with automatic retries on 429/5xx responses.
Built for LLMs — strict async, fully typed, pagination on every list tool, docstrings written as the assistant's manual.
Related MCP server: TestRail MCP Server
Quickstart
Requires Polarion 2506+ and uv — see Prerequisites. Fastest path — Claude Code:
claude mcp add mcp-server-polarion \
-e POLARION_URL=https://polarion.example.com \
-e POLARION_TOKEN=your-personal-access-token \
-- uvx mcp-server-polarionOther clients (VS Code, Claude Desktop, Cursor) — see Client Configuration.
Tools
Read
Tool | Description |
| List accessible projects |
| List documents in a project |
| List work items in a project (Lucene/SQL query) |
| List test runs in a project (Lucene query, templates filter) |
| Get test run details, optionally with the raw HTML report body |
| List a test run's execution records, one per test case iteration |
| Get one test record's execution comment and test-case revision |
| Fetch copy-paste SQL recipes for advanced queries |
| Fetch copy-paste Polarion HTML templates for raw-HTML body edits |
| Get document metadata, optionally with the raw body HTML |
| Render a document end-to-end as Markdown |
| List a document's structural parts with embedded work item metadata |
| Get work item details with the body as raw HTML |
| Get work item details with the body as Markdown |
| List a work item's outgoing or incoming links |
| List a document's attachments with file name, size, and author |
| Fetch an image attachment for viewing (bitmap as image, SVG as text) |
| List a work item's attachments with file name, size, and author |
| Fetch a work item image attachment for viewing (bitmap as image, SVG as text) |
| List a test record's attachments with file name, size, and author |
| Fetch a test record image attachment for viewing (bitmap as image, SVG as text) |
| List a document's comments with thread relationships |
| List a work item's comments with thread relationships |
| Resolve valid enum ids for a document field |
| Resolve valid enum ids for a work item field |
All list tools support pagination via page_size (1–100) and page_number parameters.
Write
Tool | Description |
| Create one or more work items in a single request |
| Update fields, body, or workflow status on one or more work items |
| Create a new document |
| Update document metadata, body, or workflow status |
| Copy a document to a new name, space, or project |
| Create one or more test runs, optionally from a template |
| Record test-case execution results on a test run |
| Update title, status, group, or custom fields on one or more test runs |
| Update result, comment, or defect link on one or more test records of a test run |
| Create one or more outgoing links from a source work item |
| Update |
| Delete one or more outgoing links from a source work item |
| Attach a work item to a document at a chosen position |
| Detach a work item from its document |
| Upload one or more local files as document attachments |
| Upload one or more local files as work item attachments |
| Upload one or more local files as test record attachments |
| Add one or more comments or replies to a document |
| Add one or more comments or replies to a work item |
| Resolve or re-open a document comment |
| Resolve or re-open a work item comment |
Example Prompts
"List the projects I can access, then show the documents in project MCPT with their types."
"List the documents in space 'Specifications' of project MCPT."
"Find every approved requirement in project MCPT whose title starts with 'Auth' and show me their owning document."
"Search project MCPT for work items where the custom field 'verification_method' is 'Test' — grab the SQL recipes first if you need a join."
"Find all work items in the SRS module of project MCPT that were changed in the last sprint."
"Read the SRS document of project MCPT and summarize each open requirement."
"Show me the structural outline of the SRS document — headings and the work items under each."
"Read work item MCPT-042 as Markdown and explain what it asks for."
"Show the outgoing and incoming links for MCPT-042 and flag any child task that is still open."
"Which requirements in the SRS document have no 'verifies' back link from a test case?"
"List the open comment threads on the SRS document and who started each."
"Create a task in project MCPT titled 'Refactor authentication module' and link it to MCPT-042 as 'relates_to'."
"Create three test-case work items in project MCPT from this checklist and link each one to MCPT-042 as 'verifies'."
"Add a new requirement under section 3.2 of the SRS document with the body I just drafted."
"Update the description of MCPT-042 with the revised text I'll paste, keeping the existing formatting."
"Add a comment on the SRS document asking the owner to clarify section 4, then reply to thread T-12 marking it resolved."
"Create a test run REG-SPRINT-7 in project MCPT from the 'Regression' template with status 'open'."
"List the valid status values for a defect in project MCPT, then move MCPT-077 to 'in_review'."
"Bump MCPT-042's priority to 90, set severity to 'major', and approve the workflow."
"Change MCPT-201 from a task to a requirement and re-apply its previous status."
"Move MCPT-201 into the SRS document right after MCPT-150."
"Detach MCPT-077 from its document so I can rework it as a standalone task."
"Mark the 'blocks' link from MCPT-042 to MCPT-099 as suspect, then delete the stale 'relates_to' link to MCPT-010."
Setup
Prerequisites
Polarion 2506 or higher is required. Earlier versions lack REST API endpoints this server depends on.
This server is distributed as a Python package and requires uv to run.
Install uv (if not already installed):
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Or via pip:
pip install uvNo other installation is needed — uvx mcp-server-polarion downloads and runs the server automatically.
Environment Variables
Variable | Description | Example |
| Base URL of your Polarion instance |
|
| Personal Access Token for authentication |
|
| Optional. Client-side request rate cap — raise it to match your deployment's throttle, or set |
|
To generate a Personal Access Token, open Polarion, click your user name, and go to My Account → Personal Access Tokens.
Client Configuration
Add to .vscode/mcp.json:
{
"servers": {
"mcp-server-polarion": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"mcp-server-polarion": {
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}Add to Cursor MCP settings:
{
"mcpServers": {
"mcp-server-polarion": {
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}Register via the claude mcp add command:
claude mcp add mcp-server-polarion \
-e POLARION_URL=https://polarion.example.com \
-e POLARION_TOKEN=your-personal-access-token \
-- uvx mcp-server-polarionContributing
Bug reports and pull requests are welcome — see CONTRIBUTING.md for branch, commit, and review conventions.
License
Available Tools
46 toolscopy_documentA
Copy a document, duplicating its structure, body, and contained work items.
Rebuilding via create_document/update_document loses the contained items. target_document_name must be free at the destination — check list_documents first. Destination defaults to the source project/space.
link_original_items_with_role is validated against the TARGET project's workitem-link-role enum; remove_outgoing_links strips links carried over from the source.
Inputs: space_id (required), project_id (required), document_name (required), target_document_name (required), +6 more. Returns: ``copy_document`` result. Location fields parsed from the copy 201.
create_documentA
Create a document in a space.
document_name must be unique in the space — a duplicate name conflicts; check list_documents first. type/status and custom_fields keys are validated on write — resolve ids via list_document_enum_options first.
Set rendering_layout_types to every work item type the document will hold — without a layout their fields do not render in the Polarion UI. Resolve those ids via list_work_item_enum_options; a later update_document must resend every type to keep.
home_page_content is Markdown (greenfield only), converted to sanitized HTML. Markdown tables get native Polarion styling; a paragraph starting 'Table:' directly after a table becomes a numbered caption widget. Post-create edits round-trip raw HTML via get_document(include_home_page_content_html=True) and update_document; add work items via move_work_item_to_document.
Inputs: type (required), title (required), space_id (required), project_id (required), +8 more. Returns: ``create_document`` result.
create_document_attachmentsA
Upload 1-10 local files as document attachments in one request.
file_path is read from local disk by the server process -- use absolute paths to readable files. file_name (default: file_path's basename) becomes the attachment id; reference it in a document body as attachment:{id} for update_document. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. Pure create -- nothing is replaced. Uploads cannot be deleted through this API, so verify file_path and file_name first. A file_name colliding with another item in the same call, or with an existing attachment on the document, rejects the whole batch -- check list_document_attachments first or pick a new file_name. NOT idempotent -- retrying a success is rejected as a duplicate, not silently merged.
Inputs: space_id (required), project_id (required), attachments (required), document_name (required), +1 more. Returns: Attachment-create result, shared by document, work item, and test record upload…
create_document_commentsA
Create one or more comments on a document in one request.
Reply: set parent_comment_id to a short id from list_document_comments (None = top-level). 'text/html' text is sent unsanitized. Always authored by the token's user. NOT idempotent — a retry duplicates. attachment:{id} image refs in text/html comments must name an existing document attachment — resolve via list_document_attachments first.
Inputs: comments (required), space_id (required), project_id (required), document_name (required), +1 more. Returns: Comment-create result.
create_test_record_attachmentsA
Upload 1-10 local files as test record attachments in one request.
For document attachments use create_document_attachments, for work item attachments use create_work_item_attachments instead. Record coordinates (project_id, test_run_id, test_case_id, iteration) match get_test_record -- verify via list_test_records first. file_path is read from local disk by the server process -- use absolute paths to readable files. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. attachment_ids in the result are server-assigned ({test_case_id}_{file_name}) and differ from the input file_name. A file_name colliding with another item in the same call, or with an existing attachment on the record, rejects the whole batch -- check list_test_record_attachments first or pick a new file_name. NOT idempotent -- retrying a success is rejected as a duplicate, not silently merged.
Inputs: project_id (required), attachments (required), test_run_id (required), test_case_id (required), +2 more. Returns: Attachment-create result, shared by document, work item, and test record upload…
create_test_recordsA
Create 1-50 test records on one test run, recording which test cases were executed with what result.
Use list_test_records to read them back; create_test_runs creates the run itself. Atomic: one bad item rejects the whole batch. Posting the same test_case_id again starts a new iteration rather than replacing it -- use separate calls, not duplicates in one batch. comment is sent verbatim in comment_format, no Markdown conversion.
Returns record_ids as full 5-segment ids -- never shortened. result is validated against the project's testing enumerations; defect must reference an existing work item. An invalid test_case_id is rejected by Polarion -- resolve via list_work_items first.
Inputs: items (required), project_id (required), test_run_id (required), dry_run. Returns: ``create_test_records`` result.
create_test_runsA
Create 1-50 test runs in one project in one bulk request.
id is required per item — never auto-generated. type/status are validated against the project's testing enumerations and template_id against existing templates (list_test_runs(templates=True)). custom_fields keys are validated against a sample of existing runs; enum-typed custom values are not (test runs have no options API). Atomic: one bad item rejects the whole batch.
Inputs: items (required), project_id (required), dry_run. Returns: ``create_test_runs`` result.
create_work_item_attachmentsA
Upload 1-10 local files as work item attachments in one request.
For document attachments use create_document_attachments instead. file_path is read from local disk by the server process -- use absolute paths to readable files. Total upload size per call is capped at 25 MiB: compress or use the Polarion portal for one oversized file, split oversized batches across calls. attachment_ids in the result are server-assigned counter-prefixed ids (e.g. 3-diagram.png) -- not predictable from file_name -- and double as the workitemimg:{id} reference tokens for the work item description body. Duplicate file_name values are allowed, both within one call and against existing attachments: each upload creates a new attachment, never a conflict. Heading-type work items accept uploads, but the portal hides the Attachments section on heading items -- attachments there are reachable only through the API. NOT idempotent -- retrying a success silently creates a duplicate; after an ambiguous failure verify with list_work_item_attachments before retrying.
Inputs: project_id (required), attachments (required), work_item_id (required), dry_run. Returns: Attachment-create result, shared by document, work item, and test record upload…
create_work_item_commentsA
Create one or more comments on a work item in one request.
Reply: set parent_comment_id to a short id from list_work_item_comments (None = top-level). Optional title sets the comment heading. 'text/html' text is sent unsanitized. Always authored by the token's user. NOT idempotent — a retry duplicates. workitemimg:{id} image refs in text/html comments must name an existing attachment — resolve via list_work_item_attachments first.
Inputs: comments (required), project_id (required), work_item_id (required), dry_run. Returns: Comment-create result.
create_work_item_linksA
Create 1-50 outgoing links from one source work item, atomically.
Role and target existence are validated before writing. Per spec: target_project_id defaults to the source, revision pins (else HEAD), suspect flags re-review. A duplicate role+target rolls back the whole batch — re-query list_work_item_links before retrying. link_ids are the delete-path ids, input order.
Phantom success: a document-attached source already has an auto-created heading link; a NEW same-role link reports created but is NOT persisted — verify with list_work_item_links.
Inputs: links (required), project_id (required), work_item_id (required), dry_run. Returns: ``create_work_item_links`` result.
create_work_itemsA
Create 1-50 work items in one project in a single bulk request.
Items are created free-floating — place into a document with move_work_item_to_document (this tool cannot). Atomic: one bad item rejects the whole batch.
description is Markdown (greenfield only); later edits are raw-HTML round-trip via get_work_item(include_description_html=True) and update_work_items — formats never mix. Markdown tables get native Polarion styling; a paragraph starting 'Table:' directly after a table becomes a numbered caption widget. Enum values and custom_fields keys are validated on write — resolve ids via list_work_item_enum_options first. Returns the new work item ids.
Inputs: items (required), project_id (required), dry_run. Returns: ``create_work_items`` result.
delete_work_item_linksADestructiveIdempotent
Delete 1-50 outgoing links from one source work item.
Outgoing only — delete a back link from its source item instead. Refs from list_work_item_links(direction="forward") or a prior create. Stale refs never fail: results split into deleted_link_ids / not_found_link_ids.
Inputs: links (required), project_id (required), work_item_id (required), dry_run. Returns: ``delete_work_item_links`` result.
get_documentARead-only
Get a document's metadata: title/type/status/timestamps/editors/custom fields.
include_home_page_content_html=True fills content_html with raw homePageContent HTML — the required source for update_document(home_page_content_html=...). That body is inline prose only — headings and embedded work items render via read_document. Never feed back a blanked (flag=False) body.
Inputs: space_id (required), project_id (required), document_name (required), include_home_page_content_html. Returns: Full Polarion document detail from ``get_document``.
get_document_attachment_contentARead-only
Fetch a document attachment's content for viewing.
PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_work_item_attachment_content for work item attachments. Use list_document_attachments to discover attachment ids, file names, and sizes.
Inputs: space_id (required), project_id (required), attachment_id (required), document_name (required).
get_html_recipesARead-only
Fetch the required HTML templates for tables, captions, links, and widgets written via update_work_items / update_document.
Any new , numbered caption, work-item / cross-reference / wiki-page link, or TOC / Table-of-Figures widget must be adapted from these templates — plain hand-written markup renders unstyled and breaks numbering. Also covers macro-id and metadata-scope caveats.
Inputs: no named parameters. Returns: Copy-paste Polarion HTML templates from ``get_html_recipes``.
get_sql_query_recipesARead-only
Fetch copy-paste SQL recipes for the list_work_items SQL:(...) prefix.
Call before writing any SQL query (document scope, custom-field, traceability); adapt a recipe instead of hand-writing joins. Includes the table schema.
Inputs: no named parameters. Returns: Copy-paste SQL recipe gallery from ``get_sql_query_recipes``.
get_test_recordARead-only
Get full detail of one test-case iteration inside a test run: execution comment and test-case revision.
Use list_test_records for run-wide summaries, get_test_run for run metadata. comment_html carries the record's raw HTML comment; plain-text comments return as-is. Verify coordinates via list_test_records if not found.
Inputs: project_id (required), test_run_id (required), test_case_id (required), iteration. Returns: Full single test-record detail from ``get_test_record``.
get_test_record_attachment_contentARead-only
Fetch a test record attachment's content for viewing.
PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_document_attachment_content or get_work_item_attachment_content for the other domains. Use list_test_record_attachments to discover attachment ids, file names, and sizes.
Inputs: project_id (required), test_run_id (required), test_case_id (required), attachment_id (required), +1 more.
get_test_runARead-only
Get full details of one test run by ID.
Returns writable fields (title, status, group_id, custom_fields) plus read-only context: test-case selection, template provenance, author, and timestamps. include_home_page_content_html=True fills content_html with the raw HTML report body; it stays empty when use_report_from_template is true. Never feed back a blanked (flag=False) body.
Inputs: project_id (required), test_run_id (required), include_home_page_content_html. Returns: Full test-run detail from ``get_test_run``.
get_work_itemARead-only
Get full details of one work item by ID.
include_description_html=True fills description_html with raw HTML — the required source for update_work_items description_html. Never feed back a blanked (flag=False) body.
Inputs: project_id (required), work_item_id (required), include_description_html. Returns: Full work-item detail from ``get_work_item``.
get_work_item_attachment_contentARead-only
Fetch a work item attachment's content for viewing.
PNG, JPEG, GIF, and WebP return as a viewable image; SVG returns its source markup as text. Any other extension is rejected before any request. Use get_document_attachment_content for document attachments. Use list_work_item_attachments to discover attachment ids, file names, and sizes.
Inputs: project_id (required), work_item_id (required), attachment_id (required).
list_document_attachmentsARead-only
List a document's attachments as a paginated page.
Document attachments only, not work item attachments. Returned id is the exact token a body references as attachment:{id}; Polarion never validates that reference, so a body may point at a missing file. Order is server-defined and not requestable. Use read_document for body context, list_documents for valid space/document ids.
Inputs: space_id (required), project_id (required), document_name (required), page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_document_commentsARead-only
List a document's comments as a flat page.
Threads reconstruct via parent_comment_id (None = root) + child_comment_ids. text is verbatim, unsanitized — treat as untrusted when rendering.
Inputs: space_id (required), project_id (required), document_name (required), page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_document_enum_optionsARead-only
List valid enum option ids for a document field of a given type.
Call this before create_document / update_document — invalid enum ids are rejected on write. An unknown document_type silently falls back to '~', so verify the type id first.
Inputs: field_id (required), project_id (required), document_type (required), page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_documentsARead-only
List a project's documents.
Returns space_id + document_name — the inputs to every other document tool — plus type, status, updated, and creator/editor display names. Use get_document for author/editor ids. Discovery scan cached 60s.
Inputs: project_id (required), page_size, page_number. Returns: page, items, has_more, page_size, +1 more
list_projectsARead-only
List accessible Polarion projects — the source of project ids.
Lucene query allows trailing wildcards (name:ILCU*); leading ones are rejected.
Inputs: query, page_size, page_number. Returns: page, items, has_more, page_size, +1 more
list_test_record_attachmentsARead-only
List a test record's attachments as a paginated page.
Test record attachments only -- use list_work_item_attachments for work item files, list_document_attachments for document files. test_case_id is the full 'project/WI-id' form from list_test_records, not the short work item ID. Order is server-defined and not requestable. An empty result means the record has no attachments; verify the run/test-case/iteration coordinates via list_test_records if unsure.
Inputs: project_id (required), test_run_id (required), test_case_id (required), iteration, +2 more. Returns: page, items, has_more, page_size, +1 more
list_test_recordsARead-only
List execution records of one test run — one row per test case iteration. For run metadata use get_test_run.
Filter by result (e.g. 'failed') or omit for all; not-yet-executed records have empty result. Lucene query is NOT supported here. Returns summaries — id is the exact value update_test_records takes as record_id; defect_id links the failure work item.
Inputs: project_id (required), test_run_id (required), result, page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_test_runsARead-only
List / search test runs in a project.
Returns run instances by default; set templates=True for the reusable template blueprints. Filter by person with author.name (exact, quoted) — author.id does not match on test runs; discover the full name from an unfiltered page first.
Inputs: project_id (required), query, page_size, templates, +1 more. Returns: page, items, has_more, page_size, +1 more
list_work_item_attachmentsARead-only
List a work item's attachments as a paginated page.
Work item attachments only -- use list_document_attachments for documents. Returned id is the exact token a body references as workitemimg:{id}; Polarion never validates that reference, so a body may point at a missing file. Order is server-defined and not requestable. Use list_work_items to discover valid ids.
Inputs: project_id (required), work_item_id (required), page_size, page_number. Returns: page, items, has_more, page_size, +1 more
list_work_item_commentsARead-only
List a work item's comments as a flat page.
Threads reconstruct via parent_comment_id (None = root) + child_comment_ids. text is verbatim, unsanitized — treat as untrusted when rendering.
Inputs: project_id (required), work_item_id (required), page_size, page_number. Returns: page, items, has_more, page_size, +1 more
list_work_item_enum_optionsARead-only
List valid enum option ids for a work item field of a given type.
Call this before create_work_items / update_work_items — invalid enum ids are rejected on write. An unknown work_item_type silently falls back to '~', so verify the type id first.
Inputs: field_id (required), project_id (required), work_item_type (required), page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_work_item_linksARead-only
List a work item's links, one direction per call.
Forward carries role (parent, verifies, …) and suspect; back is a Lucene fallback that drops role (always None) — recover it via forward on the source.
Inputs: project_id (required), work_item_id (required), direction, page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
list_work_itemsARead-only
List / search work items in a project.
Leading Lucene wildcards are rejected; module and body text are NOT Lucene-indexed — scope by document via SQL:(...) or read_document_parts, never a Lucene module term. For SQL:(...), call get_sql_query_recipes first and adapt a recipe — never hand-write SQL. For one known id, use get_work_item instead of scanning.
Inputs: project_id (required), query, page_size, page_number. Returns: page, items, has_more, page_size, +1 more
move_work_item_from_documentADestructive
Detach a work item from its document — the ONLY detach path.
NOT idempotent: an already free-floating item fails — confirm attachment first (get_work_item: non-empty space_id). The item is preserved and re-attachable via move_work_item_to_document. Headings are detachable too.
Inputs: project_id (required), work_item_id (required), dry_run. Returns: Result of ``move_work_item_to_document`` or sibling move call.
move_work_item_to_documentADestructive
Move an existing work item into a document at a given position.
THE attach path: atomically sets module and inserts a part. Headings are rejected — add headings via update_document . An item already in a document is moved, not copied.
At most one of previous_part_id (AFTER) / next_part_id (BEFORE); omit both to append. Part ids from read_document_parts.
Auto-creates one link to the enclosing heading; a later same-role create_work_item_links reports created but is NOT persisted.
Inputs: project_id (required), work_item_id (required), target_space_id (required), target_document_name (required), +3 more. Returns: Result of ``move_work_item_to_document`` or sibling move call.
read_documentARead-only
Render a document end-to-end as flowing Markdown — THE way to read a body.
Interleaves headings, work-item descriptions, and prose. Synthesis output: NEVER feed it to update_document — round-trip via get_document(include_home_page_content_html=True). For metadata-only extraction use list_work_items with SQL.
Inputs: space_id (required), project_id (required), document_name (required), page_size, +1 more. Returns: Rendered Markdown view of one page of document parts (``read_document``).
read_document_partsARead-only
List a document's structural parts in order.
Use for structure: part ids (move_work_item_to_document anchors), heading levels, per-part Markdown. For plain reading use read_document; for a document's work items use list_work_items.
Inputs: space_id (required), project_id (required), document_name (required), page_size, +1 more. Returns: page, items, has_more, page_size, +1 more
read_work_itemARead-only
Read one work item with its body rendered as Markdown.
Synthesis output — collapses Polarion anchors; NEVER feed it to update_work_items. Edits round-trip via get_work_item(include_description_html=True) instead.
Inputs: project_id (required), work_item_id (required). Returns: LLM-friendly work-item view from ``read_work_item``.
update_documentADestructiveIdempotent
Update a document's metadata or body.
PATCHes only supplied attributes — omitted fields stay unchanged; read BEFORE writing. home_page_content_html is raw Polarion HTML, sent verbatim — source from get_document(include_home_page_content_html=True); an empty string is rejected, pass '' for near-empty.
Body rules:
Inline .. auto-create heading work items — THE way to add a heading. For body text or work items use create_work_items + move_work_item_to_document, NOT this tool.
A polarion_wiki macro name=module-workitem leaves module unset — attach via move_work_item_to_document.
Tables, captions, image embeds, links, TOC/TOF widgets, page breaks must come from get_html_recipes templates, never hand-written. attachment:{id} refs must name a real attachment — confirm via list_document_attachments first.
rendering_layout_types REPLACES the type set get_document returns — pass every type to keep; existing layouts survive.
workflow_action must pair with at least one attribute. Unknown status/type ids and custom_fields keys outside the type schema are rejected — resolve ids via list_document_enum_options, or list_work_item_enum_options for rendering_layout_types.
Inputs: space_id (required), project_id (required), document_name (required), type, +9 more. Returns: ``update_document`` result.
update_document_commentAIdempotent
Resolve or re-open one document comment thread.
Root comments only — replies cannot be updated; pick a root id (parent_comment_id=None) from list_document_comments. Resolving the root resolves the whole thread. Idempotent.
Inputs: resolved (required), space_id (required), comment_id (required), project_id (required), +2 more. Returns: Comment-resolve update result, shared across comment types.
update_test_recordsADestructiveIdempotent
Set result, comment, and/or defect link on 1-50 test records of one test run in a single bulk PATCH.
Run-level fields (title, status, group_id) — use update_test_runs instead. Atomic: one bad item rejects the whole batch; no record changes.
record_id must be copied verbatim from list_test_records — never decomposed. comment is sent verbatim; Polarion stores it as text/html regardless of the comment_format sent, so a later read always shows text/html.
Returns the echoed record_ids only — re-read via list_test_records. result must already be a value the run uses (discover via list_test_records) or the write is rejected; defect_id must reference an existing work item or the write is rejected.
Inputs: items (required), project_id (required), test_run_id (required), dry_run. Returns: ``update_test_records`` result.
update_test_runsADestructiveIdempotent
Update fields on 1-50 existing test runs in one bulk PATCH; unset fields stay unchanged. Atomic: one bad item rejects the whole batch.
Writable: title, status, group_id, custom_fields. status is validated against the project's testing enumerations. custom_fields is partial; keys are validated against a sample of existing runs, values are not (test runs have no options API). finishedOn is server-managed — not settable. Returns ids only — re-read via list_test_runs.
Inputs: items (required), project_id (required), dry_run. Returns: ``update_test_runs`` result.
update_work_item_commentAIdempotent
Resolve or re-open one work item comment.
Root comments only — replies cannot be updated; pick a root id (parent_comment_id=None) from list_work_item_comments. Resolving a root flips only that comment. Idempotent.
Inputs: resolved (required), comment_id (required), project_id (required), work_item_id (required), +1 more. Returns: Comment-resolve update result, shared across comment types.
update_work_item_linkA
Set suspect and/or revision on one existing outgoing link.
Identify the link via list_work_item_links(direction="forward") — role + target address one link; copy the role exactly as listed. None = unchanged; at least one of suspect / revision required. One link per call.
Inputs: role (required), project_id (required), work_item_id (required), target_work_item_id (required), +4 more. Returns: ``update_work_item_link`` result.
update_work_itemsADestructiveIdempotent
Update fields on 1-50 existing work items in one bulk PATCH; unset fields stay unchanged. hyperlinks/assignee_ids REPLACE the stored lists: even to add ONE entry, call get_work_item on the target BEFORE updating and resubmit every existing entry plus the new one — anything omitted is silently deleted. Atomic: one bad item rejects the whole batch.
description_html is raw Polarion HTML, sent verbatim — source from get_work_item(include_description_html=True); greenfield bodies use create_work_items Markdown, formats never mix. To add a table, caption, image, link, or widget, call get_html_recipes first and adapt its template before writing description_html — hand-written table markup is rejected. workitemimg:{id} image refs must name an existing attachment — confirm via list_work_item_attachments first.
custom_fields is partial; keys outside the type schema are rejected, values are not validated — resolve via list_work_item_enum_options first. module is not settable here — use move_work_item_to_document / move_work_item_from_document. workflow_action/change_type_to apply to EVERY item; change_type_to rescopes enums to the target type and resets status. Returns ids only — re-read via get_work_item if needed.
Inputs: items (required), project_id (required), dry_run, change_type_to, +1 more. Returns: ``update_work_items`` result.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 46 tools
Tools are grouped by domain (document, work item, test record) with clear prefixes, and read vs. get vs. list are generally distinct (rendered Markdown vs. raw metadata vs. paginated listing). Some potential confusion exists between get_document/read_document and get_work_item/read_work_item, but descriptions clarify the difference.
Most tools follow a consistent verb_noun pattern (list_, get_, create_, update_) with domain prefixes (document_, work_item_, test_record_). Minor inconsistencies include singular 'comment' in update_document_comment/update_work_item_comment versus plural in list/create, and the use of 'read_' for rendering tools alongside 'get_' for metadata.
At 46 tools, the surface is very large, exceeding the 25+ threshold for a heavy set. While the domain complexity justifies many operations, the count borders on overwhelming, and some tools (e.g., separate attachment/comment tools for each entity type) could potentially be consolidated.
The tool set covers create, read, update, and list for most entities, but delete operations are largely absent: no delete_document, delete_work_item, delete_comment, or delete_attachment. The attachment descriptions explicitly state deletion is unsupported, which is a significant gap for workflows that require removing erroneous uploads.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP (Model Context Protocol) server for Codebeamer ALM. Allows Claude and other MCP clients to read and write projects, trackers, and items in Codebeamer using natural language.1924 npm9MIT
- AlicenseBqualityAmaintenanceAI-native Model Context Protocol (MCP) server for TestRail. Lets Claude, Cursor, Windsurf, and other AI assistants browse projects, create and update test cases, kick off test runs, and record results through natural-language conversation — with strongly-typed tool schemas and per-project custom field validation that helps LLMs generate valid TestRail requests on the first try.271,151 npm45Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA CLI-first Polarion ALM client with MCP server support for AI assistants, enabling natural language interaction with Polarion projects, work items, tests, and plans.12 PyPI4MIT
- AlicenseAqualityBmaintenanceA TypeScript MCP server that turns the Polarion ALM REST API into a tool-based interface for AI assistants.293144 npm6MIT