clickup-custom-mcp

Servidor MCP (Model Context Protocol) customizado para integrar o ClickUp com assistentes de IA em qualquer projeto — sem copiar configuração para cada repositório.

Diferente do MCP oficial do ClickUp (https://mcp.clickup.com/mcp, OAuth), este servidor usa a API REST do ClickUp com Personal Access Token e expõe ferramentas focadas em tasks e docs/wikis.

---

Início rápido

git clone git@github.com:lucaspsantana/clickup-mcp-server.git ~/mcp-servers/clickup-mcp-server
cd ~/mcp-servers/clickup-mcp-server
npm install
cp .env.example .env   # edite com suas credenciais
npm run setup

Reinicie os IDEs configurados. Pronto — funciona em todos os seus projetos.

Sem .env? Rode npm run setup e o script pergunta API Key e Team ID interativamente.

---

Credenciais

Você precisa de duas informações do ClickUp:

Variável	Onde obter
CLICKUP_API_KEY	Settings → Apps → API Token
CLICKUP_TEAM_ID	Número na URL: https://app.clickup.com/{team_id}/...

Onde colocar (em ordem de prioridade)

O script npm run setup busca credenciais nesta ordem:

1. Argumentos CLI — --api-key / --team-id
2. Arquivo .env na raiz do repo (recomendado)
3. Variáveis de ambiente — CLICKUP_API_KEY / CLICKUP_TEAM_ID
4. Prompt interativo — se nada acima existir

.env (recomendado)

cp .env.example .env

CLICKUP_API_KEY=pk_xxxxxxxx
CLICKUP_TEAM_ID=12345678

O .env é ignorado pelo Git. O setup grava as credenciais nos arquivos MCP dos IDEs — você configura uma vez.

Variáveis de ambiente do sistema

Alternativa ao .env — adicione ao ~/.bashrc ou ~/.zshrc:

export CLICKUP_API_KEY="pk_xxxxxxxx"
export CLICKUP_TEAM_ID="12345678"

IDEs abertos pelo menu do SO podem não herdar o .bashrc. Se isso acontecer, use .env + npm run setup (grava direto no JSON do IDE).

---

O que o npm run setup faz

1. Credenciais — lê .env, env vars, ou pergunta interativamente
2. IDEs — auto-detecta instalados (Cursor, VS Code, Claude, Kiro, Trae, Windsurf…)
3. Binário — roda npm link se clickup-custom-mcp não estiver no PATH
4. Config global — grava nos arquivos MCP de cada IDE
5. Backup — salva .bak.<timestamp> antes de sobrescrever
6. Preserva — mantém outros servidores MCP já configurados

Opções do script

npm run setup                                          # interativo
npm run setup -- --yes                                 # sem prompts (exige .env)
npm run setup -- --ides cursor,vscode                  # IDEs específicos
npm run setup -- --all-ides                            # todos (ignora auto-detecção)
npm run setup -- --include-official                    # + MCP oficial ClickUp (OAuth)
npm run setup -- --dry-run                             # simula sem escrever
npm run setup -- --api-key pk_xxx --team-id 12345678   # credenciais na CLI
clickup-mcp-setup --help                               # ajuda completa

Arquivos que o script escreve

IDE	Arquivo global (Linux)	Chave JSON
Cursor	~/.cursor/mcp.json	mcpServers
Claude Code	~/.claude.json	mcpServers
Claude Desktop	~/.config/Claude/claude_desktop_config.json	mcpServers
VS Code	~/.config/Code/User/mcp.json	servers ⚠️
Kiro	~/.kiro/settings/mcp.json	mcpServers
Trae	~/.config/Trae/User/mcp.json	mcpServers
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers

macOS: Claude Desktop → ~/Library/Application Support/Claude/claude_desktop_config.json · VS Code → ~/Library/Application Support/Code/User/mcp.json · Trae → ~/Library/Application Support/Trae/User/mcp.json

Windows: %APPDATA%\Claude\, %APPDATA%\Code\User\, %APPDATA%\Trae\User\

Auto-detecção de IDEs

O script verifica pastas/configs existentes. Se nenhum IDE for detectado, configura Cursor por padrão.

No modo interativo, confirma a lista detectada. Digite all para configurar todos os IDEs suportados.

---

Ferramentas disponíveis

Ferramenta	Descrição
clickup_list_tasks	Lista tasks por list, status, assignee ou busca
clickup_update_task	Atualiza status, nome, descrição ou assignees
clickup_list_docs	Busca Docs e Wikis no workspace
clickup_list_doc_pages	Lista páginas de um Doc/Wiki
clickup_create_doc	Cria um Doc
clickup_edit_doc	Edita conteúdo de um Doc
clickup_create_wiki	Cria um Wiki
clickup_edit_wiki	Edita conteúdo de um Wiki

---

clickup (oficial) vs clickup-custom

Você pode usar os dois simultaneamente:

npm run setup -- --include-official

	clickup (oficial)	clickup-custom (este repo)
Conexão	HTTP remoto (mcp.clickup.com)	Processo local (stdio)
Auth	OAuth / login ClickUp	Personal Access Token
Tools	Conjunto oficial ClickUp	Tasks + Docs/Wikis customizados

---

Configuração manual (alternativa)

Se preferir não usar o script, registre o binário e edite os arquivos manualmente.

1. Registrar binário

npm install
npm link
which clickup-custom-mcp

2. Bloco de configuração

Maioria dos IDEs (mcpServers):

"clickup-custom": {
  "command": "clickup-custom-mcp",
  "env": {
    "CLICKUP_API_KEY": "pk_xxxxxxxx",
    "CLICKUP_TEAM_ID": "12345678"
  }
}

VS Code (servers + type):

"clickup-custom": {
  "type": "stdio",
  "command": "clickup-custom-mcp",
  "env": {
    "CLICKUP_API_KEY": "pk_xxxxxxxx",
    "CLICKUP_TEAM_ID": "12345678"
  }
}

Kiro (não herda PATH — use caminho absoluto):

"clickup-custom": {
  "command": "/caminho/absoluto/clickup-custom-mcp",
  "env": {
    "PATH": "/caminho/do/node/bin:/usr/local/bin:/usr/bin:/bin",
    "CLICKUP_API_KEY": "pk_xxxxxxxx",
    "CLICKUP_TEAM_ID": "12345678"
  },
  "disabled": false
}

Config por IDE

Ferramenta	Global	Por projeto
Cursor	~/.cursor/mcp.json	.cursor/mcp.json
Claude Code	~/.claude.json	.mcp.json
Claude Desktop	ver tabela acima	—
VS Code	MCP: Open User Configuration	.vscode/mcp.json
Kiro	~/.kiro/settings/mcp.json	.kiro/settings/mcp.json
Trae	~/.config/Trae/User/mcp.json	.trae/mcp.json (beta)
Windsurf	~/.codeium/windsurf/mcp_config.json	—

Claude Code via CLI:

claude mcp add --scope user clickup-custom -- clickup-custom-mcp

---

Atualizar

cd ~/mcp-servers/clickup-mcp-server
git pull && npm install

O npm link não precisa ser refeito — o symlink aponta para o repo e o binário é atualizado automaticamente.

Para reconfigurar credenciais ou IDEs:

npm run setup

---

Solução de problemas

Setup falhou com "Credenciais ausentes"

Crie .env a partir de .env.example ou rode sem --yes para o modo interativo.

Servidor não aparece no IDE

1. Reinicie o IDE (a maioria só lê MCP na inicialização)
2. Valide JSON em jsonlint.com
3. Confirme o binário: which clickup-custom-mcp
4. Rebuild: npm run build

Erro CLICKUP_API_KEY is required

Credenciais não chegaram ao processo MCP. Rode npm run setup novamente — ele grava env direto no JSON do IDE.

Erro 401 / 403 da API ClickUp

• Token inválido ou revogado
• Token sem permissão no workspace
• CLICKUP_TEAM_ID incorreto

VS Code: config do Cursor não funciona

VS Code usa "servers" (não "mcpServers") e exige "type": "stdio". Use npm run setup ou adapte manualmente.

Kiro: binário não encontrado

Kiro não herda PATH. O script já usa caminho absoluto automaticamente. Confirme com which clickup-custom-mcp.

WSL2

• Use caminhos Linux (/home/...) quando IDE e MCP rodam no WSL
• Se o IDE roda no Windows e o MCP no WSL, instale Node no Windows ou use caminho WSL compatível

Teste manual do servidor

export CLICKUP_API_KEY="pk_xxx"
export CLICKUP_TEAM_ID="12345678"
clickup-custom-mcp

Erro de variável ausente = servidor OK, aguardando stdin MCP. Ctrl+C para sair.

---

Estrutura do projeto

clickup-mcp-server/
├── src/
│   ├── index.ts              # entrypoint MCP (stdio)
│   ├── client.ts             # axios + env CLICKUP_*
│   └── tools/
│       ├── tasks.ts          # list/update tasks
│       └── docs.ts           # docs e wikis
├── scripts/
│   └── setup-global.mjs      # npm run setup
├── dist/                     # gerado por npm run build
├── .env.example              # template de credenciais
├── package.json
└── tsconfig.json

---

Scripts

Comando	Descrição
npm install	Dependências + build automático (prepare)
npm run setup	Setup global interativo (recomendado)
npm run build	Compila TypeScript → dist/
npm link	Registra clickup-custom-mcp no PATH
npm start	Inicia servidor (stdio)
clickup-custom-mcp	Binário MCP (após npm link)
clickup-mcp-setup	Alias do setup (após npm link)

---

Segurança

• Nunca commite .env ou tokens no Git (.env já está no .gitignore)
• O setup grava credenciais nos configs locais dos IDEs — tratá-los como secrets
• Revogue tokens comprometidos em ClickUp Settings → Apps
• O token tem o mesmo acesso que sua conta ClickUp — trate como senha

---

Pré-requisitos

• Node.js 18+ (node --version)
• Personal Access Token do ClickUp
• Team ID (Workspace ID)