Skip to main content
Glama

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 plane

Clone 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>&1

Reinstall 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 stdio

The 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) - Optional

  • PLANE_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: When true, include user info (PII such as the display name) in logs alongside the opaque user id. Defaults to false so 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_projects

List all projects in a workspace with optional pagination and filtering

create_project

Create a new project with name, identifier, and optional configuration

retrieve_project

Retrieve a project by ID

update_project

Update a project with partial data

delete_project

Delete a project by ID

get_project_worklog_summary

Get work log summary for a project

get_project_members

Get all members of a project

update_project_features

Update features configuration of a project

Work Items

Tool Name

Description

list_work_items

List all work items in a project with optional filtering and pagination

create_work_item

Create a new work item with name, assignees, labels, and other attributes

retrieve_work_item

Retrieve a work item by ID with optional field expansion

retrieve_work_item_by_identifier

Retrieve a work item by project identifier and issue sequence number

update_work_item

Update a work item with partial data

delete_work_item

Delete a work item by ID

search_work_items

Search work items across a workspace with query string

Cycles

Tool Name

Description

list_cycles

List cycles in a project (set archived=true for archived)

create_cycle

Create a new cycle with name, dates, and owner

retrieve_cycle

Retrieve a cycle by ID

update_cycle

Update a cycle with partial data

delete_cycle

Delete a cycle by ID

manage_cycle_work_items

Add and/or remove work items on a cycle

list_cycle_work_items

List work items in a cycle

transfer_cycle_work_items

Transfer work items from one cycle to another

manage_cycle_archive

Archive or unarchive a cycle

Modules

Tool Name

Description

list_modules

List modules in a project (set archived=true for archived)

create_module

Create a new module with name, dates, status, and members

retrieve_module

Retrieve a module by ID

update_module

Update a module with partial data

delete_module

Delete a module by ID

manage_module_work_items

Add and/or remove work items on a module

list_module_work_items

List work items in a module

manage_module_archive

Archive or unarchive a module

Initiatives

Tool Name

Description

list_initiatives

List all initiatives in a workspace

create_initiative

Create a new initiative with name, dates, state, and lead

retrieve_initiative

Retrieve an initiative by ID

update_initiative

Update an initiative with partial data

delete_initiative

Delete an initiative by ID

Intake Work Items

Tool Name

Description

list_intake_work_items

List all intake work items in a project with optional pagination

create_intake_work_item

Create a new intake work item in a project

retrieve_intake_work_item

Retrieve an intake work item by work item ID with optional field expansion

update_intake_work_item

Update an intake work item with partial data

delete_intake_work_item

Delete an intake work item by work item ID

Work Item Properties

Tool Name

Description

list_work_item_properties

List work item properties for a work item type

create_work_item_property

Create a new work item property with type, settings, and validation rules

retrieve_work_item_property

Retrieve a work item property by ID

update_work_item_property

Update a work item property with partial data

delete_work_item_property

Delete a work item property by ID

Milestones

Tool Name

Description

list_milestones

List all milestones in a project

create_milestone

Create a new milestone

retrieve_milestone

Retrieve a milestone by ID

update_milestone

Update a milestone by ID

delete_milestone

Delete a milestone by ID

manage_milestone_work_items

Add and/or remove work items on a milestone

list_milestone_work_items

List work items in a milestone

Labels

Tool Name

Description

list_labels

List all labels in a project

create_label

Create a new label

retrieve_label

Retrieve a label by ID

update_label

Update a label by ID

delete_label

Delete a label by ID

States

Tool Name

Description

list_states

List all states in a project

create_state

Create a new state

retrieve_state

Retrieve a state by ID

update_state

Update a state by ID

delete_state

Delete a state by ID

Work Item Comments

Tool Name

Description

list_work_item_comments

List comments for a work item

retrieve_work_item_comment

Retrieve a specific comment for a work item

create_work_item_comment

Create a comment for a work item

update_work_item_comment

Update a comment for a work item

delete_work_item_comment

Delete a comment for a work item

Tool Name

Description

list_work_item_links

List links for a work item

retrieve_work_item_link

Retrieve a specific link for a work item

create_work_item_link

Create a link for a work item

update_work_item_link

Update a link for a work item

delete_work_item_link

Delete a link for a work item

Work Item Types

Tool Name

Description

list_work_item_types

List all work item types in a project

create_work_item_type

Create a new work item type

retrieve_work_item_type

Retrieve a work item type by ID

update_work_item_type

Update a work item type by ID

delete_work_item_type

Delete a work item type by ID

import_work_item_types_to_project

Bulk-link workspace-level work item types to a project

resolve_work_item_type

Find or create a named type for a project, auto-handling workspace vs project scope and import

Work Item Relations

Tool Name

Description

list_work_item_relations

List relations for a work item

create_work_item_relation

Create relations for a work item

remove_work_item_relation

Remove a relation from a work item

Work Item Relation Definitions

Tool Name

Description

list_work_item_relation_definitions

List workspace custom relation definitions

create_work_item_relation_definition

Create a workspace relation definition

update_work_item_relation_definition

Update a relation definition

delete_work_item_relation_definition

Delete a relation definition

Work Item Activities

Tool Name

Description

list_work_item_activities

List activities for a work item

retrieve_work_item_activity

Retrieve a specific activity for a work item

Work Logs

Tool Name

Description

list_work_logs

List work logs for a work item

create_work_log

Create a work log for a work item

update_work_log

Update a work log for a work item

delete_work_log

Delete a work log for a work item

Pages

Tool Name

Description

list_pages

List pages (workspace, or a project's if project_id given)

retrieve_page

Retrieve a page by ID (workspace, or project's if project_id given)

create_page

Create a workspace or project page

Workspaces

Tool Name

Description

get_workspace_members

Get all members of the current workspace

get_features

Get feature flags (workspace, or a project's if project_id given)

update_workspace_features

Update features of the current workspace

Users

Tool Name

Description

get_me

Get current authenticated user information

Total Tools: 100+ tools across 20 categories

Development

Running Tests

pytest

Code 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 tools
attach_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_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_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).

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_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):

  1. list_work_item_properties() → all workspace properties, one call

  2. find the property by display_name in-memory → property.id

  3. 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_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_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

    B3.4/5.0

    Scored across 177 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      A 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.
      46
      367
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      76
      17 npm
      1
      MIT