Plaky MCP Server

A Model Context Protocol server that exposes the Plaky project-management REST API to MCP-compatible AI clients (Claude Desktop, Claude Code, Cursor, etc.).

It wraps the full Plaky public API surface — spaces, boards, items/subitems, fields, comments, reactions, files, users and teams — as 26 well-described tools.

Features

• Workspace — current user, list/get users (filter by email/status/type), list/get teams
• Spaces & boards — list/get spaces, list boards, get board structure (groups, fields, allowed values)
• Items — list (with view/parent/expand filters + pagination), get, create item or subitem, delete
• Fields — update one field or many at once, by field key or title, with per-type value formats
• Comments — list, create (incl. replies), update, delete, and set emoji reactions
• Files — list, get, upload (from a local path), rename/describe, delete, download
• Clean error reporting (status + API error body), 429 rate-limit awareness, 1-indexed pagination with hasMore.

Install

npm install plaky-mcp

Or run without installing globally:

npx plaky-mcp

You need a Plaky API key (Plaky → Profile settings → API). It is sent as the X-API-Key header on every request.

Client configuration

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json)

{
  "mcpServers": {
    "plaky": {
      "command": "npx",
      "args": ["-y", "plaky-mcp"],
      "env": {
        "PLAKY_API_KEY": "your-api-key"
      }
    }
  }
}

For Claude Code you can also run:

claude mcp add plaky --env PLAKY_API_KEY=your-api-key -- npx -y plaky-mcp

Cursor

Add to your MCP settings (.cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "plaky": {
      "command": "npx",
      "args": ["-y", "plaky-mcp"],
      "env": {
        "PLAKY_API_KEY": "your-api-key"
      }
    }
  }
}

Development

git clone https://github.com/pavlealeksic/plaky-mcp.git
cd plaky-mcp
npm install
npm run build
export PLAKY_API_KEY="your-api-key"
npm start

Environment variables

| Variable | Required | Description | | ---------------- | -------- | ------------------------------------------------------ | | PLAKY_API_KEY | yes | Plaky API key, sent as X-API-Key. | | PLAKY_BASE_URL | no | Override the API base URL (default https://api.plaky.com). |

Tool reference

All tools are prefixed plaky_. IDs are integers. Typical flow: plaky_list_spaces → plaky_list_boards → plaky_get_board (to learn field keys and allowed values) → plaky_list_items / plaky_create_item / plaky_update_item_fields.

| Tool | Description | | --- | --- | | plaky_get_current_user | The API key's owner (verify auth). | | plaky_list_users / plaky_list_teams / plaky_get_team | Workspace members and teams. | | plaky_list_spaces / plaky_get_space | Spaces (optionally expand boards). | | plaky_list_boards / plaky_get_board | Boards and board structure. | | plaky_list_items / plaky_get_item / plaky_list_subitems | Read items. | | plaky_create_item / plaky_delete_item | Create item/subitem; delete item. | | plaky_update_item_field / plaky_update_item_fields | Change one / many field values. | | plaky_list_item_comments / plaky_create_item_comment / plaky_update_item_comment / plaky_delete_item_comment | Comments. | | plaky_set_comment_reactions | Set the caller's emoji reactions on a comment. | | plaky_list_item_files / plaky_get_item_file / plaky_upload_item_file / plaky_update_item_file / plaky_delete_item_file / plaky_download_item_file | File attachments. |

Field value formats

When setting fields (on create/update), keys are field keys ("status-1") or titles ("Status"). Values by type:

| Type | Example | | --- | --- | | String / Rich text | "some text" | | Number | 13.4 | | Date | "2026-01-02T18:10:15.254Z" | | Timeline | { "start": "...", "end": "..." } | | Status | "To do" or label id "1" | | Tag | ["Product", "HR"] (titles or ids) | | Link | "https://..." or { "url": "...", "displayText": "..." } | | Person | { "users": [{ "id": "1" }, { "email": "[email protected]" }], "teams": [{ "id": 1 }] } |

npm run dev    # tsx watch on src/index.ts
npm run build  # tsc -> dist/

Notes

• Rate limit: 200 requests / user / minute; exceeding it returns HTTP 429.

License

MIT