# Plaky MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
[Plaky](https://plaky.com) 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

```bash
npm install plaky-mcp
```

Or run without installing globally:

```bash
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`)

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

For Claude Code you can also run:

```bash
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):

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

## Development

```bash
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": "x@y.com" }], "teams": [{ "id": 1 }] }` |

```bash
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