Plane MCP Server
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., "@Plane MCP Server list all my assigned work items in the current cycle"
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.
Plane MCP Server
A Model Context Protocol (MCP) server for Plane integration. This server provides tools and resources for interacting with Plane through AI agents.
Features
🔧 Plane Integration: Interact with Plane APIs and services
🔌 Multiple Transports: Supports stdio, SSE, and streamable HTTP transports
🌐 Remote & Local: Works both locally and as a remote service
🛠️ Extensible: Easy to add new tools and resources
Related MCP server: Plane MCP Server
Usage
The server supports three transport methods. We recommend using uvx as it doesn't require installation.
Requirements:
Python 3.10+ (for stdio transport, via
uvx)Node.js 22+ (for remote transports, via
npx)
1. Stdio Transport (for local use)
If you have already installed makeplane/plane-mcp-server, uninstall it first:
claude mcp remove planeClone the current project to your local machine and rebuild it (uv required):
mkdir ~/Workspace/plane-mcp-server
cd ~/Workspace/plane-mcp-server
git clone git@github.com:leigangzhang/plane-mcp-server-adapter.git
uv venv .venv 2>&1 && source .venv/bin/activate && uv pip install -e . 2>&1Reinstall from the locally built plane-mcp-server:
claude mcp add plane \
-e PLANE_API_KEY=<PLANE_API_KEY> \
-e PLANE_WORKSPACE_SLUG=<PLANE_WORKSPACE_SLUG> \
-e PLANE_BASE_URL=<PLANE_ACCESS_TOKEN> \
-- ~/Workspace/plane-mcp-server/.venv/bin/plane-mcp-server stdioThe official installation method is not recommended, as it will download and build from the makeplane/plane-mcp-server repository, which has API compatibility issues with the community edition of Plane.
2. Remote HTTP Transport with OAuth
Connect to the hosted Plane MCP server using OAuth authentication.
URL: https://mcp.plane.so/http/mcp
MCP Client Configuration (for tools like Claude Desktop without native remote MCP support):
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
}
}
}Note: OAuth authentication will be handled automatically when connecting to the remote server.
3. Remote HTTP Transport using PAT Token
Connect to the hosted Plane MCP server using a Personal Access Token (PAT).
URL: https://mcp.plane.so/http/api-key/mcp
Headers:
Authorization: Bearer <PAT_TOKEN>X-Workspace-slug: <SLUG>
MCP Client Configuration (for tools like Claude Desktop without native remote MCP support):
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
"headers": {
"Authorization": "Bearer <PAT_TOKEN>",
"X-Workspace-slug": "<SLUG>"
}
}
}
}4. SSE Transport (Legacy)
⚠️ Legacy Transport: SSE (Server-Sent Events) transport is maintained for backward compatibility. New implementations should use the HTTP transport (sections 2 or 3) instead.
Connect to the hosted Plane MCP server using OAuth authentication via Server-Sent Events.
URL: https://mcp.plane.so/sse
MCP Client Configuration (for tools that support SSE transport):
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["mcp-remote@latest", "https://mcp.plane.so/sse"]
}
}
}Note: OAuth authentication will be handled automatically when connecting to the remote server. This transport is deprecated in favor of the HTTP transport.
Configuration
Authentication
The server requires authentication via environment variables:
PLANE_BASE_URL: Base URL for Plane API (default:https://api.plane.so) - OptionalPLANE_API_KEY: API key for authentication (required for stdio transport)PLANE_WORKSPACE_SLUG: Workspace slug identifier (required for stdio transport)PLANE_ACCESS_TOKEN: Access token for authentication (alternative to API key)
Example (for stdio transport):
export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"Note: For remote HTTP transports (OAuth or PAT), authentication is handled via the connection method (OAuth flow or PAT headers) and does not require these environment variables.
OAuth redirect URIs
For the OAuth HTTP/SSE transports, the server validates each client's redirect URI against an allowlist. Common MCP clients (Cursor, VS Code, Claude.ai, ChatGPT connectors, localhost) are allowed by default.
To onboard a new client without a code change or release, append extra patterns via an environment variable:
PLANE_OAUTH_ALLOWED_REDIRECT_URIS: Comma-separated redirect URI patterns appended to the built-in allowlist.
export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"Patterns support glob matching (* matches any port, path segment, or subdomain). For security, keep the host pinned and wildcard only the port/path.
Logging
The server emits structured JSON logs. Each tool call is logged with its tool name, duration, status, and (when available) the opaque user id and workspace slug.
LOG_USER_INFO: Whentrue, include user info (PII such as the display name) in logs alongside the opaque user id. Defaults tofalseso PII is never logged unless explicitly opted in. Only the OAuth and PAT (header) HTTP transports carry a display name; stdio is unaffected.
export LOG_USER_INFO="true"Available Tools
The server provides comprehensive tools for interacting with Plane. All tools use Pydantic models from the Plane SDK for type safety and validation.
Projects
Tool Name | Description |
| List all projects in a workspace with optional pagination and filtering |
| Create a new project with name, identifier, and optional configuration |
| Retrieve a project by ID |
| Update a project with partial data |
| Delete a project by ID |
| Get work log summary for a project |
| Get all members of a project |
| Update features configuration of a project |
Work Items
Tool Name | Description |
| List all work items in a project with optional filtering and pagination |
| Create a new work item with name, assignees, labels, and other attributes |
| Retrieve a work item by ID with optional field expansion |
| Retrieve a work item by project identifier and issue sequence number |
| Update a work item with partial data |
| Delete a work item by ID |
| Search work items across a workspace with query string |
Cycles
Tool Name | Description |
| List cycles in a project (set |
| Create a new cycle with name, dates, and owner |
| Retrieve a cycle by ID |
| Update a cycle with partial data |
| Delete a cycle by ID |
| Add and/or remove work items on a cycle |
| List work items in a cycle |
| Transfer work items from one cycle to another |
| Archive or unarchive a cycle |
Modules
Tool Name | Description |
| List modules in a project (set |
| Create a new module with name, dates, status, and members |
| Retrieve a module by ID |
| Update a module with partial data |
| Delete a module by ID |
| Add and/or remove work items on a module |
| List work items in a module |
| Archive or unarchive a module |
Initiatives
Tool Name | Description |
| List all initiatives in a workspace |
| Create a new initiative with name, dates, state, and lead |
| Retrieve an initiative by ID |
| Update an initiative with partial data |
| Delete an initiative by ID |
Intake Work Items
Tool Name | Description |
| List all intake work items in a project with optional pagination |
| Create a new intake work item in a project |
| Retrieve an intake work item by work item ID with optional field expansion |
| Update an intake work item with partial data |
| Delete an intake work item by work item ID |
Work Item Properties
Tool Name | Description |
| List work item properties for a work item type |
| Create a new work item property with type, settings, and validation rules |
| Retrieve a work item property by ID |
| Update a work item property with partial data |
| Delete a work item property by ID |
Milestones
Tool Name | Description |
| List all milestones in a project |
| Create a new milestone |
| Retrieve a milestone by ID |
| Update a milestone by ID |
| Delete a milestone by ID |
| Add and/or remove work items on a milestone |
| List work items in a milestone |
Labels
Tool Name | Description |
| List all labels in a project |
| Create a new label |
| Retrieve a label by ID |
| Update a label by ID |
| Delete a label by ID |
States
Tool Name | Description |
| List all states in a project |
| Create a new state |
| Retrieve a state by ID |
| Update a state by ID |
| Delete a state by ID |
Work Item Comments
Tool Name | Description |
| List comments for a work item |
| Retrieve a specific comment for a work item |
| Create a comment for a work item |
| Update a comment for a work item |
| Delete a comment for a work item |
Work Item Links
Tool Name | Description |
| List links for a work item |
| Retrieve a specific link for a work item |
| Create a link for a work item |
| Update a link for a work item |
| Delete a link for a work item |
Work Item Types
Tool Name | Description |
| List all work item types in a project |
| Create a new work item type |
| Retrieve a work item type by ID |
| Update a work item type by ID |
| Delete a work item type by ID |
| Bulk-link workspace-level work item types to a project |
| Find or create a named type for a project, auto-handling workspace vs project scope and import |
Work Item Relations
Tool Name | Description |
| List relations for a work item |
| Create relations for a work item |
| Remove a relation from a work item |
Work Item Relation Definitions
Tool Name | Description |
| List workspace custom relation definitions |
| Create a workspace relation definition |
| Update a relation definition |
| Delete a relation definition |
Work Item Activities
Tool Name | Description |
| List activities for a work item |
| Retrieve a specific activity for a work item |
Work Logs
Tool Name | Description |
| List work logs for a work item |
| Create a work log for a work item |
| Update a work log for a work item |
| Delete a work log for a work item |
Pages
Tool Name | Description |
| List pages (workspace, or a project's if |
| Retrieve a page by ID (workspace, or project's if |
| Create a workspace or project page |
Workspaces
Tool Name | Description |
| Get all members of the current workspace |
| Get feature flags (workspace, or a project's if |
| Update features of the current workspace |
Users
Tool Name | Description |
| Get current authenticated user information |
Total Tools: 100+ tools across 20 categories
Development
Running Tests
pytestCode Formatting
black plane_mcp/
ruff check plane_mcp/License
MIT License - see LICENSE for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Deprecation Notice
⚠️ The Node.js-based plane-mcp-server is deprecated and no longer maintained.
This repository represents the new Python+FastMCP based implementation of the Plane MCP server. If you were using the previous Node.js version, please migrate to this Python-based version for continued support and updates.
The new implementation offers:
Better type safety with Pydantic models
Improved performance with FastMCP
Enhanced tool coverage
Active maintenance and development
For migration assistance, please refer to the configuration examples in this README or open an issue for support.
Old Node.js Configuration (Deprecated):
If you were using the previous Node.js-based @makeplane/plane-mcp-server, your configuration looked like this:
{
"mcpServers": {
"plane": {
"command": "npx",
"args": [
"-y",
"@makeplane/plane-mcp-server"
],
"env": {
"PLANE_API_KEY": "<YOUR_API_KEY>",
"PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>"
}
}
}
}Please migrate to the new Python-based configuration shown in the Usage section above.
Available Tools
177 toolsattach_page_to_work_itemB
Link a page to a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item page_id: UUID of the page to link
Returns: WorkItemPage link object
Inputs: page_id (required), project_id (required), work_item_id (required). Returns: Work item to page link.
complete_cycleA
Complete (close) a cycle by setting its end date to today.
Plane has no explicit "complete" action — a cycle is considered complete when its end_date is in the past. This tool sets end_date to today, effectively closing the cycle.
Args: project_id: UUID of the project cycle_id: UUID of the cycle to complete
Returns: Updated Cycle object
Inputs: cycle_id (required), project_id (required). Returns: Cycle model.
count_work_itemsA
Count work items across the workspace with optional grouping.
Use this for analytics — "how many urgent items?", "distribution by state?" — without fetching full work item payloads.
Args: pql: PQL filter to scope the count (e.g. 'priority = "urgent"'). group_by: Dimension to group counts by. Supported values: state_id, state__group, priority, project_id, type_id, labels__id, assignees__id, issue_module__module_id, release_work_items__release_id, cycle_id, milestone_id, created_by, target_date, start_date. sub_group_by: Second dimension for nested grouping (requires group_by).
Returns: grouped_by: The group_by field used (null if none). sub_grouped_by: The sub_group_by field used (null if none). total_count: Total matching work items. grouped_counts: Dict of group_key → {count} or {count, sub_grouped_counts} when sub_group_by is set. Keys are UUIDs for FK fields, plain strings for priority/state__group, ISO dates for target_date/start_date, "None" for unset values.
Inputs: pql, group_by, sub_group_by. Returns: object
create_customerA
Create a customer, or update the existing one it matches (upsert).
This is an upsert, not a plain create. When external_source and external_id are both given, the customer matching them is updated; otherwise a customer with the same name is updated. A new customer is created only when neither matches — so a repeated call never duplicates.
Args: name: Name of the person or business; also the match key when no external reference is given description_html: HTML description email: Primary contact email website_url: Customer website, e.g. "https://acme.com" domain: The customer's industry — shown as "Industry" in Plane. Free text, e.g. "Retail", "e-Commerce", "Fintech", "Banking". This is NOT a web domain; the site belongs in website_url. employees: Number of employees, if the customer is a business stage: Lifecycle stage. Stored free-form, but Plane only renders: lead | sales_qualified_lead | contract_negotiation | closed_won | closed_lost contract_status: Stored free-form, but Plane only renders: active | pre_contract | signed | inactive revenue: Annual revenue the customer generates, as a string, e.g. "5000000" external_source: External system the customer came from, e.g. "salesforce" external_id: The customer's ID in that external system
Returns: The created or updated Customer
Inputs: name (required), email, stage, domain, +7 more. Returns: Customer model.
create_customer_propertyA
Create a customer property (a workspace-wide custom field on customers).
property_type, is_multi and settings are fixed once created — recreate the property to change them.
Args: name: Required, but discarded — the stored name is a slug of display_name. Pass display_name here too if you have nothing else. display_name: User-facing label. Must be unique in the workspace: it derives the property's slug, so a display name already in use is rejected. property_type: TEXT | DATETIME | DECIMAL | BOOLEAN | OPTION | RELATION | URL | EMAIL | FILE relation_type: ISSUE | USER — required when property_type=RELATION description: Property description is_required: Whether a value must be set; forces default_value to be empty default_value: Default value(s); at most one unless is_multi settings: Required for TEXT/DATETIME. TEXT: {"display_format": "single-line"|"multi-line"|"readonly"} DATETIME: {"display_format": "MMM dd, yyyy"|"dd/MM/yyyy"|"MM/dd/yyyy"|"yyyy/MM/dd"} is_active: Whether the property is active is_multi: Whether the property holds multiple values options: For OPTION type — [{"name": str, "description"?: str, "is_default"?: bool}] external_source: External system this property came from, e.g. "salesforce" external_id: The property's ID in that external system
Returns: The created CustomerProperty, including its options for OPTION type
Inputs: name (required), display_name (required), property_type (required), options, +9 more. Returns: Customer property model.
create_customer_requestA
Create a request on a customer.
Args: customer_id: UUID of the customer name: Request name description_html: HTML description link: URL associated with the request work_item_ids: UUIDs of work items addressing this request; links them to the customer as the request is created. Only settable here — use manage_customer_work_items to change links afterwards.
Returns: The created CustomerRequest. work_item_ids is never echoed back; read the links with list_customer_work_items.
Inputs: name (required), customer_id (required), link, work_item_ids, +1 more. Returns: Customer request model.
create_cycleB
Create a new cycle.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Cycle name owned_by: UUID of the user who owns the cycle description: Cycle description start_date: Cycle start date (ISO 8601 format) end_date: Cycle end date (ISO 8601 format) external_source: External system source name external_id: External system identifier timezone: Cycle timezone
Returns: Created Cycle object
Inputs: name (required), owned_by (required), project_id (required), end_date, +5 more. Returns: Cycle model.
create_initiativeA
Create a new initiative in the workspace.
Args: name: Initiative name description_html: HTML description of the initiative start_date: Initiative start date (ISO 8601 format) end_date: Initiative end date (ISO 8601 format) logo_props: Logo properties dictionary state: Initiative state (DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED) lead: UUID of the user who leads the initiative
Returns: Created Initiative object
Raises: ToolError: if the workspace's initiatives feature is disabled. Native initiatives require the feature to be enabled in workspace settings. When disabled, create an "Initiative" work item instead — the error message gives the exact steps.
Inputs: name (required), lead, state, end_date, +3 more. Returns: Initiative model.
create_intake_work_itemC
Create a new intake work item in a project.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project data: Intake work item data as a dictionary
Returns: Created IntakeWorkItem object
Inputs: data (required), project_id (required). Returns: Intake work item model.
create_labelA
Create a new label.
Args: project_id: UUID of the project name: Label name color: Label color (hex color code) description: Label description parent: UUID of the parent label (for nested labels) sort_order: Sort order for the label external_source: External system source name external_id: External system identifier
Returns: Created Label object
Inputs: name (required), project_id (required), color, parent, +4 more. Returns: Label model.
create_milestoneA
Create a new milestone.
Args: project_id: UUID of the project title: Milestone title target_date: Target date for the milestone (ISO 8601 format) external_source: External system source name external_id: External system identifier
Returns: Created Milestone object
Inputs: title (required), project_id (required), external_id, target_date, +1 more. Returns: Milestone model.
create_moduleC
Create a new module.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Module name description: Module description start_date: Module start date (ISO 8601 format) target_date: Module target/end date (ISO 8601 format) status: Module status (backlog, planned, in-progress, paused, completed, cancelled) lead: UUID of the user who leads the module members: List of user IDs who are members of the module external_source: External system source name external_id: External system identifier
Returns: Created Module object
Inputs: name (required), project_id (required), lead, status, +6 more. Returns: Module model.
create_pageA
Create a page.
Creates a project page if project_id is given, otherwise a workspace-level page.
Args: name: Page name description_html: Page content in HTML format project_id: UUID of the project. Omit to create a workspace page. access: Access level for the page (integer) color: Page color is_locked: Whether the page is locked archived_at: Archive timestamp (ISO 8601 format) view_props: View properties dictionary logo_props: Logo properties dictionary external_id: External system identifier external_source: External system source name
Returns: Created Page object
Inputs: name (required), description_html (required), color, access, +7 more. Returns: Page model.
create_projectA
Create a new project.
Args: workspace_slug: The workspace slug identifier name: Project name identifier: Project identifier (e.g., "MP" for "My Project") description: Project description project_lead: UUID of the project lead user default_assignee: UUID of the default assignee user emoji: Emoji for the project cover_image: Cover image URL or asset ID module_view: Enable module view cycle_view: Enable cycle view issue_views_view: Enable issue views view page_view: Enable page view intake_view: Enable intake view guest_view_all_features: Allow guests to view all features archive_in: Days until auto-archive close_in: Days until auto-close timezone: Project timezone external_source: External system source name external_id: External system identifier is_issue_type_enabled: Enable issue types
Returns: Created Project object
Inputs: name (required), identifier (required), emoji, close_in, +15 more. Returns: Project model.
create_project_estimateA
Create a new estimate for a project.
Args: project_id: UUID of the project name: Name of the estimate (e.g., "Story Points", "T-Shirt Sizes") type: Estimate type — "categories", "points", or "time" description: Optional description last_used: Whether this becomes the active estimate (default True) external_id: External system identifier external_source: External system source name
Returns: Created Estimate object
Inputs: name (required), project_id (required), type, last_used, +3 more. Returns: Estimate response model. Represents the sizing scale configured for a project (…
create_project_estimate_pointsA
Create estimate points for a project estimate.
Each point dict may have: value (required, max 20 chars), key (int), description, external_id, external_source.
Example: points=[ {"value": "1", "key": 0}, {"value": "2", "key": 1}, {"value": "3", "key": 2}, {"value": "5", "key": 3}, {"value": "8", "key": 4}, ]
Args: project_id: UUID of the project estimate_id: UUID of the estimate points: List of point definitions
Returns: List of created EstimatePoint objects
Inputs: points (required), project_id (required), estimate_id (required). Returns: result
create_releaseA
Create a release in the workspace. Name must be unique in the workspace.
Args: name: Release name description_html: HTML body of the release notes status: unreleased (default) | released | cancelled release_date: The date shown as "Target date" in the Plane UI, YYYY-MM-DD. Use this for the date a user calls the release's target/release date. target_date: A separate date stored on the release but not shown in the release UI. Prefer release_date unless you specifically need this field. tag_id: UUID of a release tag (version marker) to attach lead_id: UUID of the user leading the release is_prerelease: Whether this is a pre-release external_source: External system this release came from, e.g. "github" external_id: The release's ID in that external system
Returns: The created Release. Its description comes back as a nested object.
Inputs: name (required), status, tag_id, lead_id, +6 more. Returns: Release response model. `description` is returned as a nested object ({descript…
create_release_labelA
Create a release label in the workspace palette. Name must be unique.
This defines a label; attach it to a release with manage_release_labels.
Args: name: Label name color: Hex color, e.g. "#4E5355" sort_order: Position in the palette
Returns: The created ReleaseLabel
Inputs: name (required), color, sort_order. Returns: Release label response model.
create_release_tagA
Create a release tag (version marker). Version must be unique in the workspace.
Args: version: Version string, e.g. "v1.2.0" description: Optional notes about the version commit_hash: Git commit the version was cut from git_tag: Corresponding git tag name
Returns: The created ReleaseTag
Inputs: version (required), git_tag, commit_hash, description. Returns: Release tag response model. A tag is a version marker (version + optional git m…
create_stateA
Create a new state.
Args: project_id: UUID of the project name: State name color: State color (hex color code) description: State description sequence: State sequence order group: State group (e.g., backlog, unstarted, started, completed, cancelled) is_triage: Whether this is a triage state default: Whether this is the default state external_source: External system source name external_id: External system identifier
Returns: Created State object
Inputs: name (required), color (required), project_id (required), group, +6 more. Returns: State model.
create_work_itemA
Create a new work item.
Args: project_id: UUID of the project name: Work item name (required) assignees: List of user IDs to assign to the work item labels: List of label IDs to attach to the work item type_id: UUID of the work item type point: Story point value description_html: HTML description of the work item description_stripped: Plain text description. Convenience only — it is wrapped into HTML and stored as description_html (Plane derives description_stripped server-side). Ignored if description_html is set. priority: Priority level (urgent, high, medium, low, none) start_date: Start date (ISO 8601 format) target_date: Target/end date (ISO 8601 format) sort_order: Sort order value is_draft: Whether the work item is a draft external_source: External system source name external_id: External system identifier parent: UUID of the parent work item state: UUID of the state estimate_point: Estimate point value type: Work item type identifier
Returns: Created WorkItem object
Inputs: name (required), project_id (required), type, point, +15 more. Returns: Work item model.
create_work_item_commentA
Create a comment for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item comment_html: Comment content in HTML format comment_json: Comment content in JSON format access: Access level for the comment (INTERNAL or EXTERNAL) external_source: External system source name external_id: External system identifier
Returns: Created WorkItemComment object
Inputs: project_id (required), work_item_id (required), access, external_id, +3 more. Returns: Work item comment model.
create_work_item_linkB
Create a link for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item url: URL of the link
Returns: Created WorkItemLink object
Inputs: url (required), project_id (required), work_item_id (required). Returns: Work item link model.
create_work_item_propertyA
Create a new work item property.
Scope resolution:
project_id + work_item_type_id → type-scoped project property (legacy)
project_id only → project-level property (not yet linked to a type)
neither → workspace-level property
Args: display_name: Display name for the property property_type: TEXT | DATETIME | DECIMAL | BOOLEAN | OPTION | RELATION | URL | EMAIL | FILE | FORMULA project_id: UUID of the project. Omit for workspace-level property. work_item_type_id: UUID of the work item type — omit to create at project level relation_type: ISSUE | USER — required when property_type=RELATION description: Property description is_required: Whether the property is required default_value: Default value(s) for the property settings: Required for TEXT/DATETIME. TEXT: {"display_format": "single-line"|"multi-line"|"readonly"} DATETIME: {"display_format": "MMM dd, yyyy"|"dd/MM/yyyy"|"MM/dd/yyyy"|"yyyy/MM/dd"} is_active: Whether the property is active is_multi: Whether the property supports multiple values validation_rules: Validation rules dictionary external_source: External system source name external_id: External system identifier options: List of {name, color?, is_default?} dicts — for OPTION type
Returns: Created WorkItemProperty object
Inputs: display_name (required), property_type (required), options, is_multi, +11 more. Returns: Work item property model.
create_work_item_property_optionA
Create an option on a work item property.
Args: property_id: UUID of the work item property name: Display name for the option project_id: UUID of the project. Omit for workspace scope. description: Option description color: Hex color string e.g. "#FF5733" is_default: Whether this is the default option external_source: External system source name external_id: External system identifier
Returns: Created WorkItemPropertyOption object
Inputs: name (required), property_id (required), color, is_default, +4 more. Returns: Work item property option model.
create_work_item_relationA
Relate a work item to one or more targets.
Always call list_work_item_relation_definitions first and match the user's wording to an entry there. If it is a built_in_dependencies value, pass it as relation_type. If it is a custom_definitions entry, pass that definition's id as relation_definition_id and the matched outward/inward label as relation_definition_label (the label sets directionality).
Args: project_id: UUID of the project. work_item_id: UUID of the source work item. work_item_ids: UUIDs of the target work items. relation_type: A built_in_dependencies value, or None for a custom relation. relation_definition_id: UUID of the relation definition (custom relations). relation_definition_label: Definition's outward or inward label (custom relations).
Returns: List of created WorkItemWithRelationType objects.
Inputs: project_id (required), work_item_id (required), work_item_ids (required), relation_type, +2 more. Returns: result
create_work_item_relation_definitionA
Create a new workspace relation definition.
A relation definition describes a named relationship type with an outward label (how the source item describes the target) and an inward label (how the target item describes the source).
Args: name: Unique name for this relation definition. outward: Label describing the relation from the source item's perspective. inward: Label describing the relation from the target item's perspective. is_active: Whether this definition is active and available for use. color: Hex color code for UI display.
Returns: Created WorkItemRelationDefinition object.
Inputs: name (required), color, inward, outward, +1 more. Returns: Work item relation definition response model.
create_work_item_typeA
Create a new work item type.
To get a usable type for a project (e.g. "Epic"), prefer resolve_work_item_type, which finds-or-creates at the correct scope and never duplicates.
Args: name: Work item type name project_id: UUID of the project. Omit for workspace-level type. description: Work item type description project_ids: List of project IDs this type applies to is_active: Whether the type is active external_source: External system source name external_id: External system identifier
Returns: Created WorkItemType object
Inputs: name (required), is_active, project_id, description, +3 more. Returns: Work item type model.
create_work_logA
Create a work log for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item duration: Duration of work in minutes description: Description of the work performed
Returns: Created WorkItemWorkLog object
Inputs: project_id (required), work_item_id (required), duration, description. Returns: Work item work log model.
delete_customerA
Delete a customer, addressed either by ID or by its external reference.
Pass customer_id, or pass both external_source and external_id for a customer synced from an external system. Deleting by an external reference that matches nothing succeeds silently.
Args: customer_id: UUID of the customer external_source: External system the customer came from external_id: The customer's ID in that external system
Inputs: customer_id, external_id, external_source.
delete_customer_propertyA
Delete a customer property, and every customer's values for it.
Args: property_id: UUID of the customer property
Inputs: property_id (required).
delete_customer_requestA
Delete a customer request, and unlink the work items linked through it.
Args: customer_id: UUID of the customer request_id: UUID of the customer request
Inputs: request_id (required), customer_id (required).
delete_cycleC
Delete a cycle by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle
Inputs: cycle_id (required), project_id (required).
delete_initiativeA
Delete an initiative by ID.
Args: initiative_id: UUID of the initiative
Raises: ToolError: if the initiatives feature is disabled. When disabled, the initiative is an "Initiative" work item — the error gives the steps.
Inputs: initiative_id (required).
delete_intake_work_itemB
Delete an intake work item by work item ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project work_item_id: UUID of the work item (use the issue field from IntakeWorkItem response, not the intake work item ID)
Inputs: project_id (required), work_item_id (required).
delete_labelB
Delete a label by ID.
Args: project_id: UUID of the project label_id: UUID of the label
Inputs: label_id (required), project_id (required).
delete_milestoneB
Delete a milestone by ID.
Args: project_id: UUID of the project milestone_id: UUID of the milestone
Inputs: project_id (required), milestone_id (required).
delete_moduleC
Delete a module by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module
Inputs: module_id (required), project_id (required).
delete_projectB
Delete a project by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project
Inputs: project_id (required).
delete_project_estimateB
Delete the estimate for a project.
Args: project_id: UUID of the project
Inputs: project_id (required).
delete_project_estimate_pointA
Delete a single estimate point.
Args: project_id: UUID of the project estimate_id: UUID of the estimate estimate_point_id: UUID of the estimate point to delete
Inputs: project_id (required), estimate_id (required), estimate_point_id (required).
delete_releaseA
Delete a release by ID.
Args: release_id: UUID of the release
Inputs: release_id (required).
delete_release_labelA
Delete a release label from the workspace palette, detaching it everywhere.
To only remove a label from one release, use manage_release_labels with action="detach".
Args: label_id: UUID of the release label
Inputs: label_id (required).
delete_release_tagA
Delete a release tag by ID.
Args: tag_id: UUID of the release tag
Inputs: tag_id (required).
delete_stateB
Delete a state by ID.
Args: project_id: UUID of the project state_id: UUID of the state
Inputs: state_id (required), project_id (required).
delete_work_itemB
Delete a work item by ID.
Args: project_id: UUID of the project work_item_id: UUID of the work item
Inputs: project_id (required), work_item_id (required).
delete_work_item_attachmentA
Delete an attachment from a work item.
Use list_work_item_attachments to get the attachment_id.
Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment to delete
Inputs: project_id (required), work_item_id (required), attachment_id (required).
delete_work_item_commentA
Delete a comment for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment
Inputs: comment_id (required), project_id (required), work_item_id (required).
delete_work_item_linkB
Delete a link for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link
Inputs: link_id (required), project_id (required), work_item_id (required).
delete_work_item_propertyA
Delete a work item property by ID.
Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type — omit to use project-level endpoint
Inputs: work_item_property_id (required), project_id, work_item_type_id.
delete_work_item_property_optionA
Delete an option from a work item property.
Args: property_id: UUID of the work item property option_id: UUID of the option project_id: UUID of the project. Omit for workspace scope.
Inputs: option_id (required), property_id (required), project_id.
delete_work_item_property_valueA
Delete the value(s) of a custom property on a work item.
For multi-value properties, deletes all values for that property.
Args: project_id: UUID of the project work_item_id: UUID of the work item property_id: UUID of the work item property
Inputs: project_id (required), property_id (required), work_item_id (required).
delete_work_item_relation_definitionA
Delete a workspace relation definition.
Args: definition_id: UUID of the relation definition to delete.
Inputs: definition_id (required).
delete_work_item_typeA
Delete a work item type by ID.
Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope.
Inputs: work_item_type_id (required), project_id.
delete_work_logA
Delete a work log for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item work_log_id: UUID of the work log
Inputs: project_id (required), work_log_id (required), work_item_id (required).
detach_page_from_work_itemA
Remove a page link from a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item work_item_page_id: UUID of the work item page link (not the page ID)
Inputs: project_id (required), work_item_id (required), work_item_page_id (required).
get_customer_property_valuesA
Read the custom property values a customer holds.
Args: customer_id: UUID of the customer property_id: UUID of one customer property; omit to read them all
Returns: Property UUID mapped to its values. Properties with no value set, and inactive properties, are absent.
Inputs: customer_id (required), property_id. Returns: object
get_featuresA
Get feature flags.
Returns a project's features if project_id is given, otherwise the workspace's features.
Args: project_id: UUID of the project. Omit for workspace features.
Returns: ProjectFeature when project_id is given, otherwise WorkspaceFeature.
Inputs: project_id. Returns: result
get_meA
Get current user information.
Returns: UserLite object containing current user information
Inputs: no named parameters. Returns: Lite user information.
get_pql_referenceA
Return the Plane Query Language (PQL) syntax reference.
Call this when composing the pql filter for list_work_items,
list_archived_work_items, list_cycle_work_items, list_module_work_items,
or count_work_items.
Args: detail: "full" (default) returns the comprehensive reference with all operators, functions, common mistakes, and worked examples. "brief" returns the compact field/operator/function quick reference (lighter payload for simple queries).
Returns:
Dict with detail (which version was returned) and reference
(the PQL syntax text).
Inputs: detail. Returns: object
get_project_estimateA
Get the estimate configuration for a project.
Returns the active estimate system including its ID, which is required to call list_project_estimate_points.
Args: project_id: UUID of the project
Returns: Estimate object with id, name, and type fields
Inputs: project_id (required). Returns: Estimate response model. Represents the sizing scale configured for a project (…
get_project_membersA
List members of a project (filterable).
Optional filters first_name/last_name/email/display_name (case-insensitive contains), role_slug (exact), is_active, is_bot — combined with AND.
Args: project_id: UUID of the project. order_by: Sort field; prefix '-' for descending.
Returns: Paginated envelope: results (members incl. role, role_slug, is_active, is_bot). Self-hosted Plane returns all members in a single page, so next_page_results is always false.
Inputs: project_id (required), email, is_bot, order_by, +5 more. Returns: Paginated response for the project members-lite endpoint.
get_project_worklog_summaryC
Get work log summary for a project.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project
Returns: List of ProjectWorklogSummary objects containing work item IDs and durations
Inputs: project_id (required). Returns: result
get_release_changelogA
Get a release's changelog. Each release has a single changelog, created empty on first access, so this always returns one.
Args: release_id: UUID of the release
Returns: The ReleaseChangelog. Its body comes back as a nested object.
Inputs: release_id (required). Returns: Release changelog response model.
get_work_item_attachment_download_urlA
Get a presigned download URL for a work item attachment.
Returns a time-limited URL (typically valid ~1 hour) that can be opened directly in a browser or downloaded with any HTTP client — no Plane authentication required on the URL itself.
Use list_work_item_attachments first to get attachment IDs and names.
Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment
Returns: Dict with: download_url (presigned S3 URL), attachment_id, name.
Inputs: project_id (required), work_item_id (required), attachment_id (required). Returns: object
get_work_item_property_valueA
Get the value(s) of a custom property on a work item.
Use list_work_item_properties to find the property_id for a given property name (e.g. "Acceptance Criteria").
Args: project_id: UUID of the project work_item_id: UUID of the work item property_id: UUID of the work item property
Returns: Single WorkItemPropertyValueDetail for non-multi properties, or list of WorkItemPropertyValueDetail for multi-value properties
Inputs: project_id (required), property_id (required), work_item_id (required). Returns: result
get_workspace_membersA
List members of the current workspace (filterable).
Optional filters first_name/last_name/email/display_name (case-insensitive contains), role_slug (exact), is_active, is_bot — combined with AND.
Args: order_by: Sort field; prefix '-' for descending.
Returns: Paginated envelope: results (members incl. role, role_slug, is_active, is_bot). Self-hosted Plane returns all members in a single page, so next_page_results is always false.
Inputs: email, is_bot, order_by, is_active, +4 more. Returns: Paginated response for the workspace members-lite endpoint.
import_work_item_types_to_projectA
Bulk-link workspace-level work item types to a project.
Imports one or more workspace-scoped work item types into a project so that they become available for use within that project.
For the common case of getting one named type usable in a project, prefer resolve_work_item_type, which finds-or-creates and imports in one step.
Args: project_id: UUID of the project work_item_type_ids: List of workspace-level work item type UUIDs to import
Inputs: project_id (required), work_item_type_ids (required).
link_estimate_to_projectA
Link an estimate to a project, making it the active estimate system.
Args: project_id: UUID of the project estimate_id: UUID of the estimate to activate
Returns: Updated Project object
Inputs: project_id (required), estimate_id (required). Returns: Project model.
list_archived_work_itemsA
List archived work items in a project with optional PQL filtering.
Args:
project_id: UUID of the project
pql: PQL filter expression. Omit to list all archived items.
order_by: Field to sort by; prefix with - for descending
(default -archived_at).
per_page: Results per page, 1-100 (default 100).
cursor: Pagination cursor from a previous response's next_cursor.
expand: Comma-separated related fields to expand.
fields: Comma-separated sparse fieldset.
Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.
Inputs: project_id (required), pql, cursor, expand, +3 more. Returns: object
list_customer_propertiesA
List customer properties (paginated).
Customer properties are custom fields defined once per workspace and applied to every customer. Use get_customer_property_values to read what a specific customer holds for them.
Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 1000).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: cursor, per_page. Returns: Paginated response for customer properties list endpoint. All pagination fields…
list_customer_requestsA
List a customer's requests (paginated).
A customer request records something the customer asked for. The work items addressing it are read with list_customer_work_items, not from here.
Args: customer_id: UUID of the customer query: Filter to requests whose name contains this text. cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 1000).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: customer_id (required), query, cursor, per_page. Returns: Paginated response for customer requests list endpoint. All pagination fields f…
list_customersA
List customers in the workspace (paginated).
Args: query: Filter to customers whose name contains this text. cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 1000).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: query, cursor, per_page. Returns: Paginated response for customers list endpoint. All pagination fields from Pagi…
list_customer_work_itemsA
List the work items linked to a customer. Returns all of them, unpaginated.
Args: customer_id: UUID of the customer customer_request_id: Only work items linked through this request of the customer search: Filter by work item name, sequence ID, or project identifier
Returns: The linked work items
Inputs: customer_id (required), search, customer_request_id. Returns: result
list_cyclesA
List cycles in a project. Active (non-archived) cycles by default.
Args: project_id: UUID of the project archived: Set True to list archived cycles instead of active ones. status: Filter active cycles by status — "current" (running now), "upcoming" (starts later), "completed" (ended), "draft" (no dates), or "incomplete" (not yet finished). Ignored when archived is True. cursor: Pagination cursor from a previous response's next_cursor (form "{per_page}:{page}:{offset}"). Omit for the first page. per_page: Number of results per page (1-100). order_by: Field to order results by. Prefix with '-' for descending.
Returns: Paginated envelope: results (cycles) + total_count, next_cursor, next_page_results.
Inputs: project_id (required), cursor, status, archived, +2 more. Returns: result
list_cycle_work_itemsA
List work items in a cycle with optional PQL filtering.
Args:
project_id: UUID of the project
cycle_id: UUID of the cycle
pql: PQL filter expression. See field description for syntax.
Omit to list all items in the cycle.
order_by: Field to sort by; prefix with - for descending.
per_page: Results per page, 1-100 (default 25).
cursor: Pagination cursor from a previous response's next_cursor.
expand: Comma-separated related fields to expand.
fields: Comma-separated sparse fieldset.
Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.
Inputs: cycle_id (required), project_id (required), pql, cursor, +4 more. Returns: object
list_initiative_projectsA
List projects linked to an initiative.
Args: initiative_id: UUID of the initiative params: Optional query parameters (e.g., per_page, cursor)
Returns: List of linked Project objects
Inputs: initiative_id (required), params. Returns: result
list_initiativesA
List all initiatives in a workspace.
Args: params: Optional query parameters as a dictionary (e.g., per_page, cursor)
Returns: List of Initiative objects
Raises: ToolError: if the initiatives feature is disabled. When disabled, initiatives are "Initiative" work items — the error gives the steps.
Inputs: params. Returns: result
list_intake_work_itemsA
List all intake work items in a project.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project params: Optional query parameters as a dictionary (e.g., per_page, cursor)
Returns: List of IntakeWorkItem objects
Inputs: project_id (required), params. Returns: result
list_labelsA
List all labels in a project.
Args: project_id: UUID of the project params: Optional query parameters as a dictionary
Returns: List of Label objects
Inputs: project_id (required), params. Returns: result
list_milestonesC
List all milestones in a project.
Args: project_id: UUID of the project params: Optional query parameters as a dictionary
Returns: List of Milestone objects
Inputs: project_id (required), params. Returns: result
list_milestone_work_itemsA
List work items in a milestone.
Args: project_id: UUID of the project milestone_id: UUID of the milestone params: Optional query parameters as a dictionary
Returns: List of MilestoneWorkItem objects in the milestone
Inputs: project_id (required), milestone_id (required), params. Returns: result
list_modulesA
List modules in a project.
Args: project_id: UUID of the project archived: Set True to list archived modules instead of active ones. cursor: Pagination cursor from a previous response's next_cursor (form "{per_page}:{page}:{offset}"). Omit for the first page. per_page: Number of results per page (1-100). order_by: Field to order results by. Prefix with '-' for descending.
Returns: Paginated envelope: results (modules) + total_count, next_cursor, next_page_results.
Inputs: project_id (required), cursor, archived, order_by, +1 more. Returns: result
list_module_work_itemsA
List work items in a module with optional PQL filtering.
Args:
project_id: UUID of the project
module_id: UUID of the module
pql: PQL filter expression. See field description for syntax.
Omit to list all items in the module.
order_by: Field to sort by; prefix with - for descending.
per_page: Results per page, 1-100 (default 25).
cursor: Pagination cursor from a previous response's next_cursor.
expand: Comma-separated related fields to expand.
fields: Comma-separated sparse fieldset.
Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.
Inputs: module_id (required), project_id (required), pql, cursor, +4 more. Returns: object
list_pagesA
List pages.
Lists a project's pages if project_id is given, otherwise workspace-level pages.
Args: project_id: UUID of the project. Omit to list workspace pages. params: Optional query parameters as a dictionary (e.g., per_page, cursor)
Returns: List of Page objects
Inputs: params, project_id. Returns: result
list_project_estimate_pointsA
List all valid estimate points for a project.
Use this to discover the available estimate point UUIDs before calling update_work_item with an estimate_point value. Each EstimatePoint has an id (UUID to pass to update_work_item) and a value (display label such as "1", "2", "3", "5", "8" or "XS", "S", "M", "L", "XL").
Workflow: 1. Call get_project_estimate to get the estimate_id 2. Call list_project_estimate_points with that estimate_id 3. Pick the EstimatePoint whose value matches the user's intent 4. Pass that EstimatePoint.id to update_work_item(estimate_point=...)
Args: project_id: UUID of the project estimate_id: UUID of the estimate (from get_project_estimate)
Returns: List of EstimatePoint objects, each with id and value fields
Inputs: project_id (required), estimate_id (required). Returns: result
list_projectsA
List projects in a workspace (paginated).
Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-100, default 100). order_by: Sort field; prefix '-' for descending.
Returns: Paginated envelope with full project objects: results + total_count, next_cursor, next_page_results.
Inputs: cursor, order_by, per_page. Returns: Paginated response for projects.
list_release_labelsA
List release labels (paginated).
With release_id, lists the labels attached to that release. Without it, lists the workspace's whole palette of release labels.
Args: release_id: UUID of a release to scope to; omit for the workspace palette. cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (default 20).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: cursor, per_page, release_id. Returns: Paginated response for the release labels list endpoint.
list_releasesA
List releases in the workspace (paginated).
Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (default 20).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: cursor, per_page. Returns: Paginated response for the releases list endpoint.
list_release_tagsA
List release tags in the workspace (paginated).
A release tag is a version marker (e.g. "v1.2.0") plus optional git metadata, not a label. Attach one to a release via its tag_id.
Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (default 20).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: cursor, per_page. Returns: Paginated response for the release tags list endpoint.
list_release_work_itemsA
List the work items linked to a release (paginated).
Args: release_id: UUID of the release cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (default 20).
Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).
Inputs: release_id (required), cursor, per_page. Returns: Paginated response for the release work-items list endpoint.
list_rolesA
List role definitions in the workspace.
namespace="workspace" → Owner/Admin/Member/Guest; "project" → project-role defs shared across all projects (Admin/Contributor/Commenter/Guest); omit for both. slug is stable but NOT globally unique (admin/guest exist in both namespaces) — key by (namespace, slug).
Args: namespace: "workspace" or "project"; omit for both. per_page: Results per page (server default 20). cursor: Prior response's next_cursor.
Returns: Paginated envelope: results (name, slug, namespace) + pagination fields.
Inputs: cursor, per_page, namespace. Returns: Paginated response for workspace/project role definitions.
list_statesA
List all states in a project.
Args: project_id: UUID of the project params: Optional query parameters as a dictionary
Returns: List of State objects
Inputs: project_id (required), params. Returns: result
list_work_item_activitiesA
List activities for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary
Returns: List of WorkItemActivity objects
Inputs: project_id (required), work_item_id (required), params. Returns: result
list_work_item_attachmentsA
List all attachments for a work item.
Returns metadata for each attachment. To get a downloadable link for a specific attachment, use get_work_item_attachment_download_url.
Args: project_id: UUID of the project work_item_id: UUID of the work item
Returns: List of attachments, each with: id, name, size, content_type, created_at, created_by.
Inputs: project_id (required), work_item_id (required). Returns: result
list_work_item_commentsB
List comments for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary
Returns: List of WorkItemComment objects
Inputs: project_id (required), work_item_id (required), params. Returns: result
list_work_item_linksC
List links for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary
Returns: List of WorkItemLink objects
Inputs: project_id (required), work_item_id (required), params. Returns: result
list_work_item_pagesA
List all pages linked to a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item
Returns: List of WorkItemPage link objects
Inputs: project_id (required), work_item_id (required). Returns: result
list_work_item_propertiesA
List custom work item properties.
Scope resolution (highest priority first):
no args → ALL workspace-level properties (one API call)
work_item_type_id only → workspace-level properties linked to that type
project_id only → all properties in that project (any type)
project_id + work_item_type_id → properties linked to that type in that project, falling back to project-flat then workspace if empty
For PQL filtering by name, prefer calling with NO args — one workspace-wide
fetch beats iterating every work item type. Each result includes the
display_name you can match in-memory before composing cf["<id>"] in PQL.
Each result includes:
id: property UUID — use as cf[""] in PQL filters
display_name: user-facing label (e.g. "Fed", "Acceptance Criteria")
property_type: TEXT | OPTION | DECIMAL | BOOLEAN | DATETIME | RELATION | URL | EMAIL
options: for OPTION type, each option has id + name; use option id in PQL
PQL workflow for filtering by custom property (efficient path):
list_work_item_properties() → all workspace properties, one call
find the property by display_name in-memory → property.id
list_work_items(pql='cf["<property.id>"] = "<option.id>"')
Inputs: params, project_id, work_item_type_id. Returns: result
list_work_item_property_optionsA
List options for a work item property.
Args: property_id: UUID of the work item property project_id: UUID of the project. Omit for workspace scope. params: Optional query parameters
Returns: List of WorkItemPropertyOption objects
Inputs: property_id (required), params, project_id. Returns: result
list_work_item_relation_definitionsA
List every relation type usable with create_work_item_relation.
Match the user's wording against an entry here before creating a relation. built_in_dependencies are fixed scheduling/blocking types; custom_definitions are workspace-specific, each with an outward and inward label. custom_definitions are also what create/update/delete_work_item_relation_definition manage.
Args: is_default: Filter custom definitions to default/non-default only. is_active: Filter custom definitions to active/inactive only.
Returns: built_in_dependencies: relation_type values for the dependency path. custom_definitions: workspace definitions; use the id plus the matched outward or inward label.
Inputs: is_active, is_default. Returns: object
list_work_item_relationsB
List every relation for a work item.
Args: project_id: UUID of the project. work_item_id: UUID of the work item.
Returns: dependencies: Built-in dependencies grouped by the six directions. custom: Custom relations grouped by definition label.
Inputs: project_id (required), work_item_id (required). Returns: object
list_work_itemsA
List work items with optional PQL filtering.
Omit project_id to list across the entire workspace. Pass project_id to scope results to a single project.
For UUID fields (assignee, state, label, cycle, module, type, milestone) call the relevant list tool first to get the UUID.
Args:
project_id: UUID of the project. Omit for workspace-wide results.
pql: PQL filter. See field description for syntax.
order_by: Sort field; prefix - for descending (e.g. -created_at).
per_page: 1-100, default 25.
cursor: From previous response's next_cursor.
expand: Comma-separated relations to expand (e.g. assignees,labels,state).
fields: Sparse fieldset — the response contains only the fields you
name here (plus pagination metadata). Available: id, name,
sequence_id, priority, state, project, assignees, labels, type_id,
description_html, start_date, target_date, created_at, updated_at,
created_by, is_draft. Use project (not project_id) and
description_html (there is no description field); a misnamed
field is simply absent from the result.
external_id / external_source: Filter by external system.
Returns: results: Paginated list of work items. total_count: True DB total, not page-bounded — use for counts. next_cursor: Cursor for the next page. prev_cursor: Cursor for the previous page.
Inputs: pql, cursor, expand, fields, +5 more. Returns: object
list_work_item_typesA
List work item types. Omit project_id for workspace-level types.
Each result's id is the work_item_type_id needed by list_work_item_properties
to look up custom property and option UUIDs for PQL cf[] filters.
Inputs: params, project_id. Returns: result
list_work_logsB
List work logs for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary
Returns: List of WorkItemWorkLog objects
Inputs: project_id (required), work_item_id (required), params. Returns: result
manage_customer_work_itemsA
Link or unlink work items on a customer. Use list_customer_work_items to read.
Args: customer_id: UUID of the customer action: "link" to attach the work items, "unlink" to detach them work_item_ids: Work item UUIDs to link/unlink customer_request_id: Scope the links to this request of the customer. On unlink, omitting it drops every link to the work item, whichever request made it.
Returns: The customer's linked work items after the operation
Inputs: action (required), customer_id (required), work_item_ids (required), customer_request_id. Returns: result
manage_cycle_archiveA
Archive or unarchive a cycle.
Plane requires the cycle end_date to be in the past before archiving. When archive=True, this tool automatically sets end_date to today if the cycle is still active (end_date is missing or in the future), then archives it.
Args: project_id: UUID of the project cycle_id: UUID of the cycle archive: True to archive the cycle, False to unarchive it
Returns: True if the operation completed successfully
Inputs: archive (required), cycle_id (required), project_id (required). Returns: result
manage_cycle_work_itemsA
Add or remove work items on a cycle in a single call.
At least one of add_ids or remove_ids must be provided.
Args: project_id: UUID of the project cycle_id: UUID of the cycle add_ids: UUIDs of work items to add to the cycle remove_ids: UUIDs of work items to remove from the cycle
Inputs: cycle_id (required), project_id (required), add_ids, remove_ids.
manage_initiative_projectsA
Link or unlink projects of an initiative. Use list_initiative_projects to read.
Args: initiative_id: UUID of the initiative action: "add" to link the projects, "remove" to unlink them project_ids: Project UUIDs to link/unlink
Returns: The initiative's linked projects after the operation
Inputs: action (required), project_ids (required), initiative_id (required). Returns: result
manage_milestone_work_itemsA
Add or remove work items on a milestone in a single call.
At least one of add_ids or remove_ids must be provided.
Args: project_id: UUID of the project milestone_id: UUID of the milestone add_ids: UUIDs of work items to add to the milestone remove_ids: UUIDs of work items to remove from the milestone
Inputs: project_id (required), milestone_id (required), add_ids, remove_ids.
manage_module_archiveA
Archive or unarchive a module.
Args: project_id: UUID of the project module_id: UUID of the module archive: True to archive the module, False to unarchive it
Inputs: archive (required), module_id (required), project_id (required).
manage_module_work_itemsA
Add or remove work items on a module in a single call.
At least one of add_ids or remove_ids must be provided.
Args: project_id: UUID of the project module_id: UUID of the module add_ids: UUIDs of work items to add to the module remove_ids: UUIDs of work items to remove from the module
Inputs: module_id (required), project_id (required), add_ids, remove_ids.
manage_project_archiveA
Archive or unarchive a project.
Archived projects are hidden from active project lists but not deleted. All work items, cycles, and modules are preserved.
Args: project_id: UUID of the project archive: True to archive the project, False to unarchive it
Inputs: archive (required), project_id (required).
manage_release_labelsA
Attach or detach existing palette labels on a release. Use list_release_labels with release_id to read.
Args: release_id: UUID of the release action: "attach" to add the labels, "detach" to remove them label_ids: UUIDs of palette labels to attach/detach
Returns: The release's attached labels after the operation
Inputs: action (required), label_ids (required), release_id (required). Returns: result
manage_release_work_itemsA
Add or remove work items on a release. Use list_release_work_items to read.
Args: release_id: UUID of the release action: "add" to link the work items, "remove" to unlink them work_item_ids: Work item UUIDs to add/remove
Returns: The release's linked work items after the operation
Inputs: action (required), release_id (required), work_item_ids (required). Returns: result
manage_work_item_archiveA
Archive or unarchive a work item.
Only work items in a completed or cancelled state can be archived. Archived work items no longer appear in active work item lists.
Args: project_id: UUID of the project work_item_id: UUID of the work item archive: True to archive the work item, False to unarchive it
Inputs: archive (required), project_id (required), work_item_id (required).
manage_work_item_assigneeA
Add or remove a single assignee on a work item without replacing the full list.
Provide add_user_id, remove_user_id, or both. If both are given the removal is applied first, then the addition. Already-assigned users in add_user_id are silently skipped.
Args: project_id: UUID of the project work_item_id: UUID of the work item add_user_id: UUID of the user to add as assignee remove_user_id: UUID of the user to remove from assignees
Returns: Updated WorkItem object
Inputs: project_id (required), work_item_id (required), add_user_id, remove_user_id. Returns: Work item model.
manage_work_item_labelA
Add or remove a single label on a work item without replacing the full list.
Provide add_label_id, remove_label_id, or both. If both are given the removal is applied first, then the addition. Already-attached labels in add_label_id are silently skipped.
Args: project_id: UUID of the project work_item_id: UUID of the work item add_label_id: UUID of the label to add remove_label_id: UUID of the label to remove
Returns: Updated WorkItem object
Inputs: project_id (required), work_item_id (required), add_label_id, remove_label_id. Returns: Work item model.
manage_work_item_type_propertiesA
Attach or detach properties on a work item type in a single call.
At least one of attach_ids or detach_ids must be provided. Detach does not delete the property — it only removes the association.
Args: project_id: UUID of the project work_item_type_id: UUID of the work item type attach_ids: Property UUIDs to attach to the type detach_ids: Property UUIDs to detach from the type
Returns: List of attached property UUIDs if attach_ids was provided, else None
Inputs: project_id (required), work_item_type_id (required), attach_ids, detach_ids. Returns: result
read_work_item_attachmentA
Fetch an attachment's content so the LLM can read or analyze it.
Supported file types: Images (returned as vision-readable image, max 5 MB): PNG, JPEG, GIF, WEBP Text (returned as a string, max 1 MB): TXT, MD, CSV, HTML, XML, YAML, JSON
Not supported (use get_work_item_attachment_download_url instead): PDF — requires a text-extraction library (not installed) DOCX/XLSX/PPTX — binary Office formats, require extraction Audio / Video — non-textual binary formats Generic binary — executables, archives, etc.
Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment
Returns: Image object for image files, plain string for text files.
Raises: ValueError: If the file type is unsupported or the file exceeds the size limit for its category.
Inputs: project_id (required), work_item_id (required), attachment_id (required).
remove_work_item_relationA
Remove ONE relation between two work items.
A built-in dependency and a custom relation are removed independently — removing one leaves the other intact. Set is_dependency from the relation the user named (see list_work_item_relations): True for a built-in dependency (blocking, blocked_by, start/finish ordering), False for a custom relation.
Args: project_id: UUID of the project. work_item_id: UUID of the source work item. related_work_item_id: UUID of the related work item. is_dependency: True to remove a built-in dependency, False to remove a custom relation.
Inputs: project_id (required), work_item_id (required), is_dependency (required), related_work_item_id (required).
resolve_work_item_typeA
Find a work item type by name for a project, create it if missing, and guarantee it is usable inside that project. Use this to resolve the type_id for a typed work item such as an "Epic" or "Initiative" before calling create_work_item(type_id=...).
Handles workspace-level and project-level work item types automatically, so the caller never has to decide which mode the workspace is in:
If the workspace owns work item types, the type is found (or created) at the workspace level and imported into the project. Project-level creation is blocked in this mode, so importing is the only valid path.
Otherwise the type is found (or created) at the project level, enabling the project's work item types feature first if it is off.
Matching is exact (case-sensitive, whitespace-stripped); an existing type is never duplicated.
Prefer this over manually combining get_workspace_features, list_work_item_types, create_work_item_type, and import_work_item_types_to_project — it does all of that deterministically.
Args: project_id: UUID of the project the type must be usable in name: Work item type name, e.g. "Epic" or "Initiative"
Returns:
The WorkItemType. Its id is the type_id for create_work_item.
Inputs: name (required), project_id (required). Returns: Work item type model.
retrieve_customerA
Retrieve a customer by ID.
Args: customer_id: UUID of the customer
Returns: The Customer
Inputs: customer_id (required). Returns: Customer model.
retrieve_customer_propertyA
Retrieve a customer property by ID.
Args: property_id: UUID of the customer property
Returns: The CustomerProperty, including its options for OPTION type
Inputs: property_id (required). Returns: Customer property model.
retrieve_customer_requestA
Retrieve a customer request by ID.
Args: customer_id: UUID of the customer request_id: UUID of the customer request
Returns: The CustomerRequest
Inputs: request_id (required), customer_id (required). Returns: Customer request model.
retrieve_cycleA
Retrieve a cycle by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle
Returns: Cycle object
Inputs: cycle_id (required), project_id (required). Returns: Cycle model.
retrieve_initiativeA
Retrieve an initiative by ID.
Args: initiative_id: UUID of the initiative
Returns: Initiative object
Raises: ToolError: if the initiatives feature is disabled. When disabled, the initiative is an "Initiative" work item — the error gives the steps.
Inputs: initiative_id (required). Returns: Initiative model.
retrieve_intake_work_itemB
Retrieve an intake work item by work item ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project work_item_id: UUID of the work item (use the issue field from IntakeWorkItem response, not the intake work item ID) params: Optional query parameters as a dictionary (e.g., expand, fields)
Returns: IntakeWorkItem object
Inputs: project_id (required), work_item_id (required), params. Returns: Intake work item model.
retrieve_labelA
Retrieve a label by ID.
Args: project_id: UUID of the project label_id: UUID of the label
Returns: Label object
Inputs: label_id (required), project_id (required). Returns: Label model.
retrieve_milestoneA
Retrieve a milestone by ID.
Args: project_id: UUID of the project milestone_id: UUID of the milestone
Returns: Milestone object
Inputs: project_id (required), milestone_id (required). Returns: Milestone model.
retrieve_moduleA
Retrieve a module by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module
Returns: Module object
Inputs: module_id (required), project_id (required). Returns: Module model.
retrieve_pageA
Retrieve a page by ID.
Retrieves a project page if project_id is given, otherwise a workspace page.
Args: page_id: UUID of the page project_id: UUID of the project. Omit for a workspace page.
Returns: Page object
Inputs: page_id (required), project_id. Returns: Page model.
retrieve_projectB
Retrieve a project by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project
Returns: Project object
Inputs: project_id (required). Returns: Project model.
retrieve_releaseA
Retrieve a release by ID.
Args: release_id: UUID of the release
Returns: The Release
Inputs: release_id (required). Returns: Release response model. `description` is returned as a nested object ({descript…
retrieve_release_tagA
Retrieve a release tag by ID.
Args: tag_id: UUID of the release tag
Returns: The ReleaseTag
Inputs: tag_id (required). Returns: Release tag response model. A tag is a version marker (version + optional git m…
retrieve_roleA
Retrieve a role definition by ID.
Args: role_id: UUID of the role.
Returns: Role (name, slug, namespace).
Inputs: role_id (required). Returns: Workspace or project role definition. The API returns additional fields (``id``…
retrieve_stateA
Retrieve a state by ID.
Args: project_id: UUID of the project state_id: UUID of the state
Returns: State object
Inputs: state_id (required), project_id (required). Returns: State model.
retrieve_work_itemB
Retrieve a work item by ID.
Args: project_id: UUID of the project work_item_id: UUID of the work item expand: Comma-separated fields to expand (e.g., "assignees,labels,state") fields: Comma-separated fields to include in response external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by
Returns: WorkItemDetail object with expanded relationships
Inputs: project_id (required), work_item_id (required), expand, fields, +3 more. Returns: Detailed work item with expanded relationships.
retrieve_work_item_activityA
Retrieve a specific activity for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item activity_id: UUID of the activity
Returns: WorkItemActivity object
Inputs: project_id (required), activity_id (required), work_item_id (required). Returns: Work item activity model.
retrieve_work_item_by_identifierA
Retrieve a work item by its full identifier (project prefix + sequence number).
The identifier must be in PROJECT-N format where PROJECT is the project's identifier string and N is the sequence number. Both parts are required.
Valid sparse fields values include: id, name, sequence_id, priority,
state, project, workspace, parent, assignees, labels, type_id,
start_date, target_date, created_at, updated_at, created_by,
updated_by, is_draft, external_source, external_id, estimate_point.
Use project (not project_id) to get the project UUID.
If you need the project UUID from a short identifier like "SHO",
use list_projects() instead — it returns id and identifier
for every project.
Args: work_item_identifier: Full work item identifier in PROJECT-N format expand: Comma-separated fields to expand (e.g., "assignees,labels,state") fields: Comma-separated sparse fieldset (see valid values above) external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by
Returns: WorkItemDetail object with expanded relationships
Inputs: work_item_identifier (required), expand, fields, order_by, +2 more. Returns: Detailed work item with expanded relationships.
retrieve_work_item_commentA
Retrieve a specific comment for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment
Returns: WorkItemComment object
Inputs: comment_id (required), project_id (required), work_item_id (required). Returns: Work item comment model.
retrieve_work_item_linkA
Retrieve a specific link for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link
Returns: WorkItemLink object
Inputs: link_id (required), project_id (required), work_item_id (required). Returns: Work item link model.
retrieve_work_item_propertyA
Retrieve a work item property by ID.
Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type — omit to use project-level endpoint
Returns: WorkItemProperty object
Inputs: work_item_property_id (required), project_id, work_item_type_id. Returns: Work item property model.
retrieve_work_item_property_optionA
Retrieve a single option from a work item property.
Args: property_id: UUID of the work item property option_id: UUID of the option project_id: UUID of the project. Omit for workspace scope.
Returns: WorkItemPropertyOption object
Inputs: option_id (required), property_id (required), project_id. Returns: Work item property option model.
retrieve_work_item_typeA
Retrieve a work item type by ID.
Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope.
Returns: WorkItemType object
Inputs: work_item_type_id (required), project_id. Returns: Work item type model.
search_work_itemsA
Search work items by text across a workspace.
Matches on work item name, sequence id, and project identifier (not
description). For structured filtering (priority, state, assignee,
dates, etc.) use list_work_items with a PQL expression.
Args: query: Free-text string matched against name, sequence id, and project identifier expand: Comma-separated list of related fields to expand in response fields: Comma-separated list of fields to include in response external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by. Prefix with '-' for descending
Returns: WorkItemSearch object containing search results
Inputs: query (required), expand, fields, order_by, +2 more. Returns: Work item search results.
set_customer_property_valuesA
Set a customer's custom property values, replacing any current ones.
Only the properties named are touched; the rest keep their values. Every value is a string, whatever the property's type: TEXT/URL/EMAIL/FILE: the text DATETIME: "YYYY-MM-DD" DECIMAL: the number as a string, e.g. "12.5" BOOLEAN: "True" or "False" OPTION/RELATION: the option or related record's UUID Pass a single-item list for properties that are not is_multi.
Args: customer_id: UUID of the customer values: Property UUID mapped to its new values, e.g. {"<property_id>": ["Enterprise"]}
Inputs: values (required), customer_id (required).
set_work_item_property_valueA
Set (create or update) the value of a custom property on a work item.
Acts as an upsert — creates the value if it does not exist, updates it if it does. For multi-value properties (is_multi=True), replaces all existing values with the new ones.
Value types by property type: TEXT/URL/EMAIL/FILE: string DATETIME: string (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS) DECIMAL: int or float BOOLEAN: true or false OPTION/RELATION (single): UUID string OPTION/RELATION (multi, is_multi=True): list of UUID strings
Args: project_id: UUID of the project work_item_id: UUID of the work item property_id: UUID of the work item property value: The value to set (type depends on the property type — see above) external_id: Optional external identifier for syncing external_source: Optional external source name (e.g. "github", "jira")
Returns: Single WorkItemPropertyValueDetail for non-multi properties, or list of WorkItemPropertyValueDetail for multi-value properties
Inputs: value (required), project_id (required), property_id (required), work_item_id (required), +2 more. Returns: result
transfer_cycle_work_itemsC
Transfer work items from one cycle to another.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the source cycle new_cycle_id: UUID of the target cycle to transfer issues to
Inputs: cycle_id (required), project_id (required), new_cycle_id (required).
update_customerA
Update a customer by ID. Only the fields you pass are changed.
Args: customer_id: UUID of the customer name: Name of the person or business description_html: HTML description email: Primary contact email website_url: Customer website, e.g. "https://acme.com" domain: The customer's industry — shown as "Industry" in Plane. Free text, e.g. "Retail", "e-Commerce", "Fintech", "Banking". This is NOT a web domain; the site belongs in website_url. employees: Number of employees, if the customer is a business stage: Lifecycle stage. Stored free-form, but Plane only renders: lead | sales_qualified_lead | contract_negotiation | closed_won | closed_lost contract_status: Stored free-form, but Plane only renders: active | pre_contract | signed | inactive revenue: Annual revenue the customer generates, as a string, e.g. "5000000" logo_props: Logo properties external_source: External system the customer came from external_id: The customer's ID in that external system
Returns: The updated Customer
Inputs: customer_id (required), name, email, stage, +9 more. Returns: Customer model.
update_customer_propertyA
Update a customer property. Only the fields you pass are changed.
property_type, is_multi and settings cannot be changed after creation — delete and recreate the property instead.
Args: property_id: UUID of the customer property display_name: User-facing label. Also re-slugs the property's internal name, so it must stay unique in the workspace. relation_type: ISSUE | USER — only for RELATION properties description: Property description is_required: Whether a value must be set; forces default_value to be empty default_value: Default value(s); at most one unless the property is is_multi is_active: Whether the property is active options: For OPTION type — [{"id": str, ...}] to edit an existing option, or [{"name": str, ...}] without an id to add one external_source: External system this property came from external_id: The property's ID in that external system
Returns: The updated CustomerProperty
Inputs: property_id (required), options, is_active, description, +6 more. Returns: Customer property model.
update_customer_requestA
Update a customer request. Only the fields you pass are changed.
Work item links cannot be changed here — use manage_customer_work_items with this request_id as customer_request_id.
Args: customer_id: UUID of the customer request_id: UUID of the customer request name: Request name description_html: HTML description link: URL associated with the request
Returns: The updated CustomerRequest
Inputs: request_id (required), customer_id (required), link, name, +1 more. Returns: Customer request model.
update_cycleA
Update a cycle by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle name: Cycle name description: Cycle description start_date: Cycle start date (ISO 8601 format) end_date: Cycle end date (ISO 8601 format) owned_by: UUID of the user who owns the cycle external_source: External system source name external_id: External system identifier timezone: Cycle timezone
Returns: Updated Cycle object
Inputs: cycle_id (required), project_id (required), name, end_date, +6 more. Returns: Cycle model.
update_initiativeA
Update an initiative by ID.
Args: initiative_id: UUID of the initiative name: Initiative name description_html: HTML description of the initiative start_date: Initiative start date (ISO 8601 format) end_date: Initiative end date (ISO 8601 format) logo_props: Logo properties dictionary state: Initiative state (DRAFT, PLANNED, ACTIVE, COMPLETED, CLOSED) lead: UUID of the user who leads the initiative
Returns: Updated Initiative object
Raises: ToolError: if the initiatives feature is disabled. When disabled, the initiative is an "Initiative" work item — the error gives the steps.
Inputs: initiative_id (required), lead, name, state, +4 more. Returns: Initiative model.
update_intake_work_itemA
Update an intake work item, including triage status.
Status values: -2 = pending (default/unreviewed) -1 = declined 0 = snoozed (requires snoozed_till date) 1 = accepted (converts intake item to active work item) 2 = duplicate (requires duplicate_to work item ID)
Args: project_id: UUID of the project work_item_id: UUID of the work item (use the issue field from IntakeWorkItem response, not the intake work item ID) status: Triage status (-2=pending, -1=declined, 0=snoozed, 1=accepted, 2=duplicate) snoozed_till: ISO 8601 date string, required when status=0 duplicate_to: UUID of the work item this duplicates, required when status=2 source: Source identifier source_email: Source email address
Returns: Updated IntakeWorkItem object
Inputs: project_id (required), work_item_id (required), source, status, +3 more. Returns: Intake work item model.
update_labelB
Update a label by ID.
Args: project_id: UUID of the project label_id: UUID of the label name: Label name color: Label color (hex color code) description: Label description parent: UUID of the parent label (for nested labels) sort_order: Sort order for the label external_source: External system source name external_id: External system identifier
Returns: Updated Label object
Inputs: label_id (required), project_id (required), name, color, +5 more. Returns: Label model.
update_milestoneA
Update a milestone by ID.
Args: project_id: UUID of the project milestone_id: UUID of the milestone title: Milestone title target_date: Target date for the milestone (ISO 8601 format) external_source: External system source name external_id: External system identifier
Returns: Updated Milestone object
Inputs: project_id (required), milestone_id (required), title, external_id, +2 more. Returns: Milestone model.
update_moduleB
Update a module by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module name: Module name description: Module description start_date: Module start date (ISO 8601 format) target_date: Module target/end date (ISO 8601 format) status: Module status (backlog, planned, in-progress, paused, completed, cancelled) lead: UUID of the user who leads the module members: List of user IDs who are members of the module external_source: External system source name external_id: External system identifier
Returns: Updated Module object
Inputs: module_id (required), project_id (required), lead, name, +7 more. Returns: Module model.
update_projectA
Update a project by ID.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Project name description: Project description project_lead: UUID of the project lead user default_assignee: UUID of the default assignee user identifier: Project identifier emoji: Emoji for the project cover_image: Cover image URL or asset ID network: Project visibility (0=secret, 2=public) module_view: Enable module view cycle_view: Enable cycle view issue_views_view: Enable issue views view page_view: Enable page view intake_view: Enable intake view guest_view_all_features: Allow guests to view all features archive_in: Days until auto-archive close_in: Days until auto-close timezone: Project timezone external_source: External system source name external_id: External system identifier is_issue_type_enabled: Enable issue types is_time_tracking_enabled: Enable time tracking default_state: UUID of the default state estimate: Estimate configuration
Returns: Updated Project object
Inputs: project_id (required), name, emoji, network, +20 more. Returns: Project model.
update_project_estimateB
Update the estimate for a project.
Args: project_id: UUID of the project name: New name for the estimate description: New description external_id: External system identifier external_source: External system source name
Returns: Updated Estimate object
Inputs: project_id (required), name, description, external_id, +1 more. Returns: Estimate response model. Represents the sizing scale configured for a project (…
update_project_estimate_pointA
Update a single estimate point.
Args: project_id: UUID of the project estimate_id: UUID of the estimate estimate_point_id: UUID of the estimate point to update value: New display value (max 20 chars, e.g. "XL", "13") key: New sort key (integer) description: New description external_id: External system identifier external_source: External system source name
Returns: Updated EstimatePoint object
Inputs: project_id (required), estimate_id (required), estimate_point_id (required), key, +4 more. Returns: Estimate point response model. Represents an individual value within an estimat…
update_project_featuresA
Update features of a project.
Args: workspace_slug: The workspace slug identifier project_id: UUID of the project modules: Enable/disable modules feature cycles: Enable/disable cycles feature views: Enable/disable views feature pages: Enable/disable pages feature intakes: Enable/disable intakes feature work_item_types: Enable/disable work item types feature
Returns: Updated ProjectFeature object
Inputs: project_id (required), pages, views, cycles, +3 more. Returns: Project feature model.
update_releaseA
Update a release by ID. Only the fields you pass are changed.
Args: release_id: UUID of the release name: Release name description_html: HTML body of the release notes status: unreleased | released | cancelled release_date: The date shown as "Target date" in the Plane UI, YYYY-MM-DD. Use this for the date a user calls the release's target/release date. target_date: A separate date stored on the release but not shown in the release UI. Prefer release_date unless you specifically need this field. tag_id: UUID of a release tag to attach lead_id: UUID of the user leading the release is_prerelease: Whether this is a pre-release
Returns: The updated Release
Inputs: release_id (required), name, status, tag_id, +5 more. Returns: Release response model. `description` is returned as a nested object ({descript…
update_release_changelogA
Update a release's changelog body.
The changelog UI renders from description_json, so plain text passed as description_stripped is also converted into a matching ProseMirror doc; otherwise the editor would show nothing.
Args: release_id: UUID of the release description_html: HTML body of the changelog description_stripped: Plain text body. Convenience only — it is wrapped into both HTML (description_html) and a ProseMirror doc (description_json) so it renders in the changelog editor. Ignored if description_html is set. description_json: Optional ProseMirror doc. Pass this for rich content; it wins over the doc generated from description_stripped.
Returns: The updated ReleaseChangelog
Inputs: release_id (required), description_html, description_json, description_stripped. Returns: Release changelog response model.
update_release_labelA
Update a release label in the palette. Only the fields you pass are changed.
Args: label_id: UUID of the release label name: Label name color: Hex color, e.g. "#4E5355" sort_order: Position in the palette
Returns: The updated ReleaseLabel
Inputs: label_id (required), name, color, sort_order. Returns: Release label response model.
update_release_tagA
Update a release tag by ID. Only the fields you pass are changed.
Args: tag_id: UUID of the release tag version: Version string, e.g. "v1.2.0" description: Notes about the version commit_hash: Git commit the version was cut from git_tag: Corresponding git tag name
Returns: The updated ReleaseTag
Inputs: tag_id (required), git_tag, version, commit_hash, +1 more. Returns: Release tag response model. A tag is a version marker (version + optional git m…
update_stateB
Update a state by ID.
Args: project_id: UUID of the project state_id: UUID of the state name: State name color: State color (hex color code) description: State description sequence: State sequence order group: State group (e.g., backlog, unstarted, started, completed, cancelled) is_triage: Whether this is a triage state default: Whether this is the default state external_source: External system source name external_id: External system identifier
Returns: Updated State object
Inputs: state_id (required), project_id (required), name, color, +7 more. Returns: State model.
update_work_itemA
Update a work item by ID.
Args: project_id: UUID of the project work_item_id: UUID of the work item name: Work item name assignees: List of user IDs to assign to the work item labels: List of label IDs to attach to the work item type_id: UUID of the work item type point: Story point value description_html: HTML description of the work item description_stripped: Plain text description. Convenience only — it is wrapped into HTML and stored as description_html (Plane derives description_stripped server-side). Ignored if description_html is set. priority: Priority level (urgent, high, medium, low, none) start_date: Start date (ISO 8601 format) target_date: Target/end date (ISO 8601 format) sort_order: Sort order value is_draft: Whether the work item is a draft external_source: External system source name external_id: External system identifier parent: UUID of the parent work item state: UUID of the state estimate_point: Estimate point value type: Work item type identifier
Returns: Updated WorkItem object
Inputs: project_id (required), work_item_id (required), name, type, +16 more. Returns: Work item model.
update_work_item_commentB
Update a comment for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment comment_html: Comment content in HTML format comment_json: Comment content in JSON format access: Access level for the comment (INTERNAL or EXTERNAL) external_source: External system source name external_id: External system identifier
Returns: Updated WorkItemComment object
Inputs: comment_id (required), project_id (required), work_item_id (required), access, +4 more. Returns: Work item comment model.
update_work_item_linkB
Update a link for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link url: Updated URL of the link
Returns: Updated WorkItemLink object
Inputs: link_id (required), project_id (required), work_item_id (required), url. Returns: Work item link model.
update_work_item_propertyA
Update a work item property by ID.
Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type — required when project_id is provided display_name: Display name for the property property_type: TEXT | DATETIME | DECIMAL | BOOLEAN | OPTION | RELATION | URL | EMAIL | FILE | FORMULA relation_type: ISSUE | USER — required when updating to RELATION description: Property description is_required: Whether the property is required default_value: Default value(s) for the property settings: Required when changing type to TEXT/DATETIME. TEXT: {"display_format": "single-line"|"multi-line"|"readonly"} DATETIME: {"display_format": "MMM dd, yyyy"|"dd/MM/yyyy"|"MM/dd/yyyy"|"yyyy/MM/dd"} is_active: Whether the property is active is_multi: Whether the property supports multiple values validation_rules: Validation rules dictionary external_source: External system source name external_id: External system identifier
Returns: Updated WorkItemProperty object
Inputs: work_item_property_id (required), is_multi, settings, is_active, +11 more. Returns: Work item property model.
update_work_item_property_optionA
Update an option on a work item property.
Args: property_id: UUID of the work item property option_id: UUID of the option project_id: UUID of the project. Omit for workspace scope. name: Display name for the option description: Option description color: Hex color string e.g. "#FF5733" is_default: Whether this is the default option external_source: External system source name external_id: External system identifier
Returns: Updated WorkItemPropertyOption object
Inputs: option_id (required), property_id (required), name, color, +5 more. Returns: Work item property option model.
update_work_item_relation_definitionA
Update an existing workspace relation definition.
Args: definition_id: UUID of the relation definition to update. name: New name for this definition. outward: Updated outward label. inward: Updated inward label. is_active: Updated active status. color: Updated hex color code.
Returns: Updated WorkItemRelationDefinition object.
Inputs: definition_id (required), name, color, inward, +2 more. Returns: Work item relation definition response model.
update_work_item_typeA
Update a work item type by ID.
Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope. name: Work item type name description: Work item type description project_ids: List of project IDs this type applies to is_active: Whether the type is active external_source: External system source name external_id: External system identifier
Returns: Updated WorkItemType object
Inputs: work_item_type_id (required), name, is_active, project_id, +4 more. Returns: Work item type model.
update_work_logA
Update a work log for a work item.
Args: project_id: UUID of the project work_item_id: UUID of the work item work_log_id: UUID of the work log duration: Duration of work in minutes description: Description of the work performed
Returns: Updated WorkItemWorkLog object
Inputs: project_id (required), work_log_id (required), work_item_id (required), duration, +1 more. Returns: Work item work log model.
update_workspace_featuresA
Update features of the current workspace.
Args: project_grouping: Enable/disable project grouping feature initiatives: Enable/disable initiatives feature teams: Enable/disable teams feature customers: Enable/disable customers feature wiki: Enable/disable wiki feature pi: Enable/disable PI (Program Increment) feature
Returns: Updated WorkspaceFeature object
Inputs: pi, wiki, teams, customers, +2 more. Returns: Workspace feature model. All fields are optional so a caller can toggle a singl…
upload_work_item_attachment_from_urlA
Fetch a file from a public URL and attach it to a work item.
The MCP server downloads the file server-side and uploads it to Plane via the standard three-step presigned S3 flow. The source URL must be publicly accessible without authentication and must not resolve to a private/internal network address.
Args: project_id: UUID of the project work_item_id: UUID of the work item url: Publicly accessible URL of the file to attach (e.g. a GitHub raw URL, public S3 link, or direct download link) name: Override the filename. Defaults to the filename in the URL path.
Returns: Created attachment metadata: id, name, size, content_type.
Inputs: url (required), project_id (required), work_item_id (required), name. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 177 tools
Each tool targets a distinct resource and action; even the many list_* variants (cycle/module/milestone/release/customer work items) are clearly differentiated by name and description. The handful of manage_* tools are each scoped to a unique association type, so there is no meaningful overlap.
The vast majority follow a consistent verb_noun pattern (list_, create_, retrieve_, update_, delete_). Minor deviations exist: get_ is used for some reads (get_me, get_features, get_project_members) while retrieve_ is used for resource fetches, and read_work_item_attachment breaks the pattern, but the conventions are still predictable and readable.
177 tools is an extreme mismatch for an MCP server surface; even large API client servers rarely warrant this many. Agents will struggle to select from such a huge menu, and the count far exceeds the recommended upper bound.
CRUD/lifecycle coverage is nearly complete for all major resources (projects, work items, cycles, modules, initiatives, labels, states, milestones, releases, customers, properties, types), including specialized sub-resources like comments, attachments, relations, and work logs. The only notable gaps are missing update/delete for pages and a few workspace-level operations.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with Plane.so, allowing them to manage projects and issues through Plane's API for streamlined project management workflows.640MIT

Plane MCP Serverofficial
AlicenseBqualityBmaintenanceA Model Context Protocol server that enables AI interfaces to seamlessly interact with Plane's project management system, allowing management of projects, issues, states, and other work items through a standardized API.46367MIT- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that enables LLMs to interact with Plane.so, allowing them to manage projects and issues through Plane's API. Using this server, LLMs like Claude can directly interact with your project management workflows while maintaining user control and security.7617 npm1MIT
- AlicenseCqualityDmaintenanceMCP server for Plane integration, enabling AI agents to interact with Plane APIs and services for project management tasks.100MIT