Skip to main content
Glama

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

CI Publish PyPI Python 3.13+ License: MIT

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.

mcp-server-polarion demo

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-polarion

Other clients (VS Code, Claude Desktop, Cursor) — see Client Configuration.

Tools

Read

Tool

Description

list_projects

List accessible projects

list_documents

List documents in a project

list_work_items

List work items in a project (Lucene/SQL query)

list_test_runs

List test runs in a project (Lucene query, templates filter)

get_test_run

Get test run details, optionally with the raw HTML report body

list_test_records

List a test run's execution records, one per test case iteration

get_test_record

Get one test record's execution comment and test-case revision

get_sql_query_recipes

Fetch copy-paste SQL recipes for advanced queries

get_html_recipes

Fetch copy-paste Polarion HTML templates for raw-HTML body edits

get_document

Get document metadata, optionally with the raw body HTML

read_document

Render a document end-to-end as Markdown

read_document_parts

List a document's structural parts with embedded work item metadata

get_work_item

Get work item details with the body as raw HTML

read_work_item

Get work item details with the body as Markdown

list_work_item_links

List a work item's outgoing or incoming links

list_document_attachments

List a document's attachments with file name, size, and author

get_document_attachment_content

Fetch an image attachment for viewing (bitmap as image, SVG as text)

list_work_item_attachments

List a work item's attachments with file name, size, and author

get_work_item_attachment_content

Fetch a work item image attachment for viewing (bitmap as image, SVG as text)

list_test_record_attachments

List a test record's attachments with file name, size, and author

get_test_record_attachment_content

Fetch a test record image attachment for viewing (bitmap as image, SVG as text)

list_document_comments

List a document's comments with thread relationships

list_work_item_comments

List a work item's comments with thread relationships

list_document_enum_options

Resolve valid enum ids for a document field

list_work_item_enum_options

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_work_items

Create one or more work items in a single request

update_work_items

Update fields, body, or workflow status on one or more work items

create_document

Create a new document

update_document

Update document metadata, body, or workflow status

copy_document

Copy a document to a new name, space, or project

create_test_runs

Create one or more test runs, optionally from a template

create_test_records

Record test-case execution results on a test run

update_test_runs

Update title, status, group, or custom fields on one or more test runs

update_test_records

Update result, comment, or defect link on one or more test records of a test run

create_work_item_links

Create one or more outgoing links from a source work item

update_work_item_link

Update suspect / revision on one outgoing link

delete_work_item_links

Delete one or more outgoing links from a source work item

move_work_item_to_document

Attach a work item to a document at a chosen position

move_work_item_from_document

Detach a work item from its document

create_document_attachments

Upload one or more local files as document attachments

create_work_item_attachments

Upload one or more local files as work item attachments

create_test_record_attachments

Upload one or more local files as test record attachments

create_document_comments

Add one or more comments or replies to a document

create_work_item_comments

Add one or more comments or replies to a work item

update_document_comment

Resolve or re-open a document comment

update_work_item_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 uv

No other installation is needed — uvx mcp-server-polarion downloads and runs the server automatically.

Environment Variables

Variable

Description

Example

POLARION_URL

Base URL of your Polarion instance

https://polarion.example.com

POLARION_TOKEN

Personal Access Token for authentication

your-personal-access-token

POLARION_MAX_REQUESTS_PER_SECOND

Optional. Client-side request rate cap — raise it to match your deployment's throttle, or set 0 to disable pacing. Writes keep a fixed extra pause regardless (default: 1)

1

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-polarion

Contributing

Bug reports and pull requests are welcome — see CONTRIBUTING.md for branch, commit, and review conventions.

License

MIT

Available Tools

46 tools
copy_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_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.

get_documentA
Read-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_contentA
Read-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_recipesA
Read-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_recipesA
Read-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_recordA
Read-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_contentA
Read-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_runA
Read-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_itemA
Read-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_contentA
Read-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_attachmentsA
Read-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_commentsA
Read-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_optionsA
Read-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_documentsA
Read-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_projectsA
Read-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_attachmentsA
Read-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_recordsA
Read-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_runsA
Read-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_attachmentsA
Read-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_commentsA
Read-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_optionsA
Read-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_itemsA
Read-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_documentA
Destructive

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_documentA
Destructive

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_documentA
Read-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_partsA
Read-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_itemA
Read-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_documentA
DestructiveIdempotent

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_commentA
Idempotent

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_recordsA
DestructiveIdempotent

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_runsA
DestructiveIdempotent

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_commentA
Idempotent

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_itemsA
DestructiveIdempotent

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

    A3.9/5.0

    Scored across 46 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness2/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      AI-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.
      27
      1,151 npm
      45
      Apache 2.0