What Polarion version is required?
Polarion 2506 or higher is required. Earlier versions lack the REST API endpoints this server depends on.
P
Polarion MCP Server
@devemberx
Polarion MCP Server について
MCP server for Polarion ALM — read and write documents, work items, test runs, traceability links, and comments from any MCP-compatible AI assistant
#polarion#mcp
Polarion MCP Server の設定
以下の設定を使って、このサーバーを MCP 対応クライアントに追加してください。
{
"mcpServers": {
"mcp-server-polarion": {
"command": "uvx",
"args": [
"mcp-server-polarion"
],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}Polarion MCP Server のツール
46List 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 '<p></p>' for near-empty. Body rules: - Inline <h1>..<h4> 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 <div> 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 <hN>. 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.
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.
List accessible Polarion projects — the source of project ids. Lucene query allows trailing wildcards (name:ILCU*); leading ones are rejected.
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.
Fetch the required HTML templates for tables, captions, links, and widgets written via update_work_items / update_document. Any new <table>, 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
概要
What is Polarion MCP?
Polarion MCP is a Model Context Protocol server for Polarion ALM. It enables AI assistants to read documents, work items, and traceability links, and to create, update, and reorganize work items directly from a Polarion instance.
How to use Polarion MCP?
Requires Polarion 2506 or higher, Python 3.13+, and the uv package manager. Set environment variables POLARION_URL and POLARION_TOKEN, then run via uvx mcp-server-polarion. For Claude Code use claude mcp add; for other clients (VS Code, Claude Desktop, Cursor) add a configuration entry with the same environment variables.
Key features of Polarion MCP
- 24 tools covering read and write across documents, work items, links, and comments.
- Render documents and work items as Markdown for AI consumption.
- Search with Lucene queries or SQL via recipes.
- Create, update, and manage work items, documents, links, and comments.
- Safe writes with
dry_runparameter and pre-write validation. - All list tools support pagination (page_size 1–100).
Use cases of Polarion MCP
- Discover accessible projects and list documents with their types.
- Search for work items using Lucene or SQL, then read and summarize them.
- Create work items, link them to existing items, and attach them to documents.
- Update work item fields, status, and workflow, or reorganize document structure.
- Add and resolve comments on documents to track discussions.
よくある質問
What dependencies are needed to run it?
Requires Python 3.13+ and the `uv` package manager. The server is distributed as a Python package and runs via `uvx`, which automatically downloads and executes it.
How is authentication handled?
Authentication uses a Personal Access Token passed via the `POLARION_TOKEN` environment variable. The Polarion base URL is set in `POLARION_URL`.
Does the server support write operations safely?
Yes. Every write tool supports a `dry_run` parameter, and pre-write guards validate fields, enum values, and link targets before sending requests to Polarion.
What transports does the server use?
The server uses stdio transport, communicating with clients through standard input/output streams as typical for MCP servers.
「その他」の他のコンテンツ
Awesome Mlops
visengerA curated list of references for MLOps
14.0K
Soar Flight Booking MCP
Soar Flight Booking MCP is a remote MCP server available at https://mcp.soar.flights.
MaxKB
1Panel-dev🔥 MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。
22.0K
Volley.sh
VolleyA good sequence diagram can solve almost any communication problem in engineering. Volley lets your agent write them as plain text, with the real request and response payloads on every arrow. It checks its own syntax wi
Sequential Thinking
modelcontextprotocolModel Context Protocol Servers
88.2K
コメント