Clickup Comment Style

clickup-rich-comments

Your ClickUp MCP posts ## broken comments. This fixes them. Auto-upgrades every agent comment to native rich text — headers, bold, lists, code. Works with Claude Code and Cursor.

This repo ships a post-hook plus an optional skill/plugin named clickup-comment-style (the install id in /plugin install ...).

The problem

Your agent writes a nicely formatted comment:

## Deploy steps
1. Run `migrate`
2. Restart the worker

ClickUp shows your team this — raw, unrendered:

## Deploy steps
1. Run `migrate`
2. Restart the worker

Same text. The ## and 1. never render: the MCP only writes plain comment_text, and ClickUp doesn't parse Markdown there.

What renders / what doesn't

Quickstart

git clone https://github.com/TaricaTarica/clickup-rich-comments.git
cd clickup-rich-comments
./install.sh

The installer checks prerequisites, guides you through CLICKUP_API_TOKEN setup, and configures hooks for Cursor and Claude Code automatically. Takes about two minutes.

Requirements: python3 only (hooks parse the payload in Python — no jq, no pip packages).

Install

⚠️ Pick one install method. If you install a plugin, don't also run ./install.sh (or merge hooks manually) — you'd run the upgrade twice per comment.

/plugin marketplace add TaricaTarica/clickup-rich-comments

/plugin install clickup-comment-style@clickup-rich-comments

ln -sf "$(pwd)/plugin-cursor" ~/.cursor/plugins/local/clickup-comment-style
# Developer: Reload Window → verify rules, skills, and hooks in Settings

claude plugin marketplace add TaricaTarica/clickup-rich-comments

/plugin install clickup-comment-style@clickup-rich-comments

{
  "version": 1,
  "hooks": {
    "afterMCPExecution": [
      {
        "command": "/ABSOLUTE/PATH/to/clickup-comment-style/hooks/cursor.sh"
      }
    ]
  }
}

chmod +x hooks/*.sh scripts/*.sh

python3 scripts/merge_claude_hooks.py ~/.claude/settings.json "$(pwd)/hooks/claude-code.sh"

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__.*__clickup_create(_task)?_comment",
        "hooks": [
          {
            "type": "command",
            "command": "/ABSOLUTE/PATH/to/clickup-comment-style/hooks/claude-code.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

How it works

Agent calls clickup_create_task_comment (MCP)
    → comment_text posted (partial render: backticks + URLs only)

Post-hook fires automatically (claude-code.sh / cursor.sh)
    → clickup_rich_comment.py converts text → ClickUp ops
    → PUT /api/v2/comment/{comment_id} with {"comment": [...]}

ClickUp UI shows full rich text (headers, bold, lists, code blocks)

The MCP OAuth token is not accessible to local hooks. The upgrade uses a Personal API Token (pk_...) via CLICKUP_API_TOKEN.

Why this exists

The MCP only writes comment_text — a plain string with minimal inline rendering. Native formatting (headers, lists, code blocks) lives in the separate comment field as a Quill-delta ops array, which the MCP does not expose. This hook reads comment_text after the MCP call and rewrites the comment via the documented PUT endpoint. See ClickUp comment formatting. Screenshots are rendered inline as type:image ops built from REST attachment metadata.

Reference

Claude Code vs Cursor

Security

Hooks run without a sandbox — they execute with your user permissions, the same as any local shell script Cursor or Claude Code invokes.

What the hook does:

1. Reads the MCP tool payload from stdin (tool name, comment text, comment ID).
2. If the tool is clickup_create_task_comment and the call succeeded, calls clickup_rich_comment.py.
3. The Python script sends one PUT request to https://api.clickup.com/api/v2/comment/{id} using CLICKUP_API_TOKEN from your environment.
4. On any error (missing token, API failure), the hook logs to stderr and exits 0 — your agent session is never blocked.

The repo contains no credentials. Review hooks/cursor.sh, hooks/claude-code.sh, and hooks/clickup_rich_comment.py before installing.

Step-by-step: get your CLICKUP_API_TOKEN

The installer handles this interactively, but here is the full manual path:

1. Open ClickUp Settings

Click your avatar (bottom-left) → Settings.

2. Copy your Personal API Token

Go to the Apps tab. Under API Token, click Generate (or Copy if you already have one).

The token starts with pk_.

3. Export for the current session

export CLICKUP_API_TOKEN='pk_...'

4. Persist across sessions

Add to your shell profile so every terminal (and IDE hook process) has the token:

zsh (~/.zshrc):

echo 'export CLICKUP_API_TOKEN='"'"'pk_...'"'" >> ~/.zshrc
source ~/.zshrc

bash (~/.bashrc):

echo 'export CLICKUP_API_TOKEN='"'"'pk_...'"'" >> ~/.bashrc
source ~/.bashrc

5. Verify

echo $CLICKUP_API_TOKEN
# should print: pk_...

Never commit your token. Use environment variables or your shell profile — not a .env file in a repo.

Verify it works

Test the converter directly

export CLICKUP_API_TOKEN='pk_...'
python3 hooks/clickup_rich_comment.py '<existing_comment_id>' <<'EOF'
## Test Section
- `foo()` — does something
  ref: https://example.com/docs

**IMPORTANTE**
One config record (`customrecord_acme_config`) per account.
EOF

Open the task in ClickUp — the comment should show a header, bullet list, inline code, and bold text.

End-to-end via agent

1. Ask your agent to post a comment on a ClickUp task via MCP.
2. Open the task in ClickUp.
3. Confirm headers, lists, and code blocks render natively.

If formatting is still plain, check the Hooks output channel in Cursor or hook stderr logs.

Troubleshooting

Discover the MCP tool name (optional)

The default regex matcher mcp__.*__clickup_create(_task)?_comment usually works without discovery. If you need an exact matcher:

1. python3 scripts/merge_claude_hooks.py --suggest-matcher — hints from local MCP config or debug log.
2. Or temporarily point Cursor afterMCPExecution to scripts/detect-mcp-tool-name.sh, post a test comment, read ~/.cursor/clickup-mcp-debug.log.

Repository layout

├── .claude-plugin/
│   └── marketplace.json              # Claude Code marketplace catalog
├── .cursor-plugin/
│   └── marketplace.json              # Cursor marketplace catalog
├── plugin/                           # installable Claude Code plugin
│   ├── .claude-plugin/plugin.json
│   ├── hooks/hooks.json
│   ├── scripts/claude-code.sh
│   ├── scripts/clickup_rich_comment.py  → symlink to hooks/
│   └── SKILL.md                      → symlink to repo root
├── plugin-cursor/                    # installable Cursor plugin
│   ├── .cursor-plugin/plugin.json
│   ├── hooks/hooks.json
│   ├── scripts/cursor.sh             → symlink to hooks/
│   ├── scripts/clickup_rich_comment.py  → symlink to hooks/
│   ├── skills/clickup-comment-style/SKILL.md  → symlink to repo root
│   └── rules/clickup-comment-style.mdc  → symlink to ../../.cursor/rules/
├── install.sh                        # interactive setup (universal fallback)
├── README.md
├── LICENSE
├── .env.example
├── assets/
│   └── README.md                     # demo GIF recording spec
├── hooks/
│   ├── clickup_rich_comment.py       # text → ops + PUT (source of truth)
│   ├── claude-code.sh
│   └── cursor.sh
├── config-examples/
│   ├── claude-settings.json
│   └── cursor-hooks.json
├── scripts/
│   ├── merge_claude_hooks.py
│   ├── detect-mcp-tool-name.sh
│   └── sync-plugins.sh               # provision plugin symlinks
├── SKILL.md                          # optional agent style guide
├── .cursor/rules/clickup-comment-style.mdc
└── CONTRIBUTING.md

Limitations

• Preprocessor does not cover every edge case — see CONTRIBUTING.md.
• Inline @mentions are not converted (use MCP assignee parameter).
• PUT with comment ops is documented in comment formatting but not fully in the public OpenAPI spec.
• Cursor hooks run synchronously.
• Re-running the hook overwrites the comment with ops derived from comment_text (idempotent).

Contributing

See CONTRIBUTING.md.

License

MIT