{
  "markdown": "<!-- mcp-name: io.github.devemberx/mcp-server-polarion -->\n\n<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/devemberx/mcp-server-polarion/main/.github/assets/icon.png\" alt=\"mcp-server-polarion\" width=\"140\">\n\n# mcp-server-polarion\n\n**Talk to your Polarion — AI reads, writes, and reorganizes documents, work items, test runs, and traceability links.**\n\n[Features](#features) · [Quickstart](#quickstart) · [Tools](#tools) · [Example Prompts](#example-prompts) · [Setup](#setup)\n\n[![CI](https://github.com/devemberx/mcp-server-polarion/actions/workflows/ci.yml/badge.svg)](https://github.com/devemberx/mcp-server-polarion/actions/workflows/ci.yml)\n[![Publish](https://github.com/devemberx/mcp-server-polarion/actions/workflows/publish.yml/badge.svg?event=push)](https://github.com/devemberx/mcp-server-polarion/actions/workflows/publish.yml)\n[![PyPI](https://img.shields.io/pypi/v/mcp-server-polarion)](https://pypi.org/project/mcp-server-polarion/)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n</div>\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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.\n\n![mcp-server-polarion demo](https://raw.githubusercontent.com/devemberx/mcp-server-polarion/main/.github/assets/demo.gif)\n\n## Features\n\n- **46 tools** covering read and write across documents, work items, test runs, traceability links, comments, and attachments.\n- **Read** — render documents as Markdown, search with Lucene or SQL, walk incoming/outgoing links, resolve enum options.\n- **Write** — create and update work items, documents, and test runs, manage links, reorganize document structure, post comments.\n- **Safe writes** — every write tool supports `dry_run`, and pre-write guards validate fields, enum values, and link targets before hitting Polarion.\n- **Plays nice with your server** — requests are serialized and paced to a configurable rate cap, with automatic retries on 429/5xx responses.\n- **Built for LLMs** — strict async, fully typed, pagination on every list tool, docstrings written as the assistant's manual.\n\n## Quickstart\n\nRequires **Polarion 2506+** and [**uv**](https://docs.astral.sh/uv/) — see [Prerequisites](#prerequisites). Fastest path — Claude Code:\n\n```bash\nclaude mcp add mcp-server-polarion \\\n  -e POLARION_URL=https://polarion.example.com \\\n  -e POLARION_TOKEN=your-personal-access-token \\\n  -- uvx mcp-server-polarion\n```\n\nOther clients (VS Code, Claude Desktop, Cursor) — see [Client Configuration](#client-configuration).\n\n## Tools\n\n### Read\n\n<!-- tool-table:read:start -->\n| Tool | Description |\n|---|---|\n| `list_projects` | List accessible projects |\n| `list_documents` | List documents in a project |\n| `list_work_items` | List work items in a project (Lucene/SQL query) |\n| `list_test_runs` | List test runs in a project (Lucene query, templates filter) |\n| `get_test_run` | Get test run details, optionally with the raw HTML report body |\n| `list_test_records` | List a test run's execution records, one per test case iteration |\n| `get_test_record` | Get one test record's execution comment and test-case revision |\n| `get_sql_query_recipes` | Fetch copy-paste SQL recipes for advanced queries |\n| `get_html_recipes` | Fetch copy-paste Polarion HTML templates for raw-HTML body edits |\n| `get_document` | Get document metadata, optionally with the raw body HTML |\n| `read_document` | Render a document end-to-end as Markdown |\n| `read_document_parts` | List a document's structural parts with embedded work item metadata |\n| `get_work_item` | Get work item details with the body as raw HTML |\n| `read_work_item` | Get work item details with the body as Markdown |\n| `list_work_item_links` | List a work item's outgoing or incoming links |\n| `list_document_attachments` | List a document's attachments with file name, size, and author |\n| `get_document_attachment_content` | Fetch an image attachment for viewing (bitmap as image, SVG as text) |\n| `list_work_item_attachments` | List a work item's attachments with file name, size, and author |\n| `get_work_item_attachment_content` | Fetch a work item image attachment for viewing (bitmap as image, SVG as text) |\n| `list_test_record_attachments` | List a test record's attachments with file name, size, and author |\n| `get_test_record_attachment_content` | Fetch a test record image attachment for viewing (bitmap as image, SVG as text) |\n| `list_document_comments` | List a document's comments with thread relationships |\n| `list_work_item_comments` | List a work item's comments with thread relationships |\n| `list_document_enum_options` | Resolve valid enum ids for a document field |\n| `list_work_item_enum_options` | Resolve valid enum ids for a work item field |\n<!-- tool-table:read:end -->\n\nAll list tools support pagination via `page_size` (1–100) and `page_number` parameters.\n\n### Write\n\n<!-- tool-table:write:start -->\n| Tool | Description |\n|---|---|\n| `create_work_items` | Create one or more work items in a single request |\n| `update_work_items` | Update fields, body, or workflow status on one or more work items |\n| `create_document` | Create a new document |\n| `update_document` | Update document metadata, body, or workflow status |\n| `copy_document` | Copy a document to a new name, space, or project |\n| `create_test_runs` | Create one or more test runs, optionally from a template |\n| `create_test_records` | Record test-case execution results on a test run |\n| `update_test_runs` | Update title, status, group, or custom fields on one or more test runs |\n| `update_test_records` | Update result, comment, or defect link on one or more test records of a test run |\n| `create_work_item_links` | Create one or more outgoing links from a source work item |\n| `update_work_item_link` | Update `suspect` / `revision` on one outgoing link |\n| `delete_work_item_links` | Delete one or more outgoing links from a source work item |\n| `move_work_item_to_document` | Attach a work item to a document at a chosen position |\n| `move_work_item_from_document` | Detach a work item from its document |\n| `create_document_attachments` | Upload one or more local files as document attachments |\n| `create_work_item_attachments` | Upload one or more local files as work item attachments |\n| `create_test_record_attachments` | Upload one or more local files as test record attachments |\n| `create_document_comments` | Add one or more comments or replies to a document |\n| `create_work_item_comments` | Add one or more comments or replies to a work item |\n| `update_document_comment` | Resolve or re-open a document comment |\n| `update_work_item_comment` | Resolve or re-open a work item comment |\n<!-- tool-table:write:end -->\n\n## Example Prompts\n\n<details open>\n<summary><b>Discovery & search</b></summary>\n\n> \"List the projects I can access, then show the documents in project MCPT with their types.\"\n\n> \"List the documents in space 'Specifications' of project MCPT.\"\n\n> \"Find every approved requirement in project MCPT whose title starts with 'Auth' and show me their owning document.\"\n\n> \"Search project MCPT for work items where the custom field 'verification_method' is 'Test' — grab the SQL recipes first if you need a join.\"\n\n> \"Find all work items in the SRS module of project MCPT that were changed in the last sprint.\"\n\n</details>\n\n<details>\n<summary><b>Reading & summarizing</b></summary>\n\n> \"Read the SRS document of project MCPT and summarize each open requirement.\"\n\n> \"Show me the structural outline of the SRS document — headings and the work items under each.\"\n\n> \"Read work item MCPT-042 as Markdown and explain what it asks for.\"\n\n> \"Show the outgoing and incoming links for MCPT-042 and flag any child task that is still open.\"\n\n> \"Which requirements in the SRS document have no 'verifies' back link from a test case?\"\n\n> \"List the open comment threads on the SRS document and who started each.\"\n\n</details>\n\n<details>\n<summary><b>Creating & editing</b></summary>\n\n> \"Create a task in project MCPT titled 'Refactor authentication module' and link it to MCPT-042 as 'relates_to'.\"\n\n> \"Create three test-case work items in project MCPT from this checklist and link each one to MCPT-042 as 'verifies'.\"\n\n> \"Add a new requirement under section 3.2 of the SRS document with the body I just drafted.\"\n\n> \"Update the description of MCPT-042 with the revised text I'll paste, keeping the existing formatting.\"\n\n> \"Add a comment on the SRS document asking the owner to clarify section 4, then reply to thread T-12 marking it resolved.\"\n\n> \"Create a test run REG-SPRINT-7 in project MCPT from the 'Regression' template with status 'open'.\"\n\n</details>\n\n<details>\n<summary><b>Workflow & reorganization</b></summary>\n\n> \"List the valid status values for a defect in project MCPT, then move MCPT-077 to 'in_review'.\"\n\n> \"Bump MCPT-042's priority to 90, set severity to 'major', and approve the workflow.\"\n\n> \"Change MCPT-201 from a task to a requirement and re-apply its previous status.\"\n\n> \"Move MCPT-201 into the SRS document right after MCPT-150.\"\n\n> \"Detach MCPT-077 from its document so I can rework it as a standalone task.\"\n\n> \"Mark the 'blocks' link from MCPT-042 to MCPT-099 as suspect, then delete the stale 'relates_to' link to MCPT-010.\"\n\n</details>\n\n## Setup\n\n### Prerequisites\n\n> **Polarion 2506 or higher** is required. Earlier versions lack REST API endpoints this server depends on.\n\nThis server is distributed as a Python package and requires [**uv**](https://docs.astral.sh/uv/) to run.\n\n**Install uv** (if not already installed):\n\n```bash\n# macOS / Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nOr via pip:\n\n```bash\npip install uv\n```\n\nNo other installation is needed — `uvx mcp-server-polarion` downloads and runs the server automatically.\n\n### Environment Variables\n\n| Variable | Description | Example |\n|---|---|---|\n| `POLARION_URL` | Base URL of your Polarion instance | `https://polarion.example.com` |\n| `POLARION_TOKEN` | Personal Access Token for authentication | `your-personal-access-token` |\n| `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` |\n\nTo generate a Personal Access Token, open Polarion, click your user name, and go to **My Account → Personal Access Tokens**.\n\n### Client Configuration\n\n<details>\n<summary><b>VS Code (GitHub Copilot)</b></summary>\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"mcp-server-polarion\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-polarion\"],\n      \"env\": {\n        \"POLARION_URL\": \"https://polarion.example.com\",\n        \"POLARION_TOKEN\": \"your-personal-access-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Claude Desktop</b></summary>\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-polarion\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-polarion\"],\n      \"env\": {\n        \"POLARION_URL\": \"https://polarion.example.com\",\n        \"POLARION_TOKEN\": \"your-personal-access-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Cursor</b></summary>\n\nAdd to Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-polarion\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-polarion\"],\n      \"env\": {\n        \"POLARION_URL\": \"https://polarion.example.com\",\n        \"POLARION_TOKEN\": \"your-personal-access-token\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Claude Code</b></summary>\n\nRegister via the `claude mcp add` command:\n\n```bash\nclaude mcp add mcp-server-polarion \\\n  -e POLARION_URL=https://polarion.example.com \\\n  -e POLARION_TOKEN=your-personal-access-token \\\n  -- uvx mcp-server-polarion\n```\n\n</details>\n\n## Contributing\n\nBug reports and pull requests are welcome — see [CONTRIBUTING.md](.github/CONTRIBUTING.md) for branch, commit, and review conventions.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 12412,
  "sha": "6a3597e4f8cb4374971546e8754492454e47be221dfa2bfecdbcf834a0171c42",
  "repo_slug": "devemberx/mcp-server-polarion",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_devemberx_mcp_server_polarion_b3d6c676/readme"
}