clickup-markdown-mcp

EN: MCP server for ClickUp with Markdown import/export, environment discovery, and task tools for AI assistants.

PT-BR: Servidor MCP para ClickUp com importação/exportação em Markdown, descoberta de ambiente e ferramentas de tarefas para assistentes de IA.

Note on the npm package name: The name clickup-mcp-server is already used on npm by another project. This package is published as clickup-markdown-mcp. The functionality is the same: MCP over stdio plus a CLI for Markdown workflows.

English

Features

• MCP (stdio): Full tool surface for lists, tasks, time entries, bulk updates, and import_from_md (create sprints and subtasks from tasks.md content).
• CLI: clickup-mcp-cli — discover list metadata, validate/import/export Markdown, close tasks, list custom fields.
• Config: CLICKUP_API_TOKEN or .clickup-mcp.json (see below).

Quick start with npx (MCP server)

Use this in Cursor, Claude Desktop, or any MCP host that spawns a local command.

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "clickup-markdown-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_your_token_here"
      }
    }
  }
}

• npx -y clickup-markdown-mcp runs the stdio MCP server (dist/index.js).
• For repeated use, npx caches the package; keep your token only in env, not in the repo.

CLI via npx

The CLI binary is clickup-mcp-cli (same install, different executable):

npx -y -p clickup-markdown-mcp clickup-mcp-cli -- help
npx -y -p clickup-markdown-mcp clickup-mcp-cli discover --list <LIST_ID>
npx -y -p clickup-markdown-mcp clickup-mcp-cli validate path/to/tasks.md
npx -y -p clickup-markdown-mcp clickup-mcp-cli import path/to/tasks.md --parent <PARENT_TASK_ID> --list <LIST_ID>

Configuration

| Method | Details | |--------|---------| | Environment | CLICKUP_API_TOKEN (required). Optional: CLICKUP_DEFAULT_LIST_ID, CLICKUP_DEFAULT_ASSIGNEES (comma-separated user IDs). | | File | .clickup-mcp.json in the current directory or in the user home folder. Example: { "apiToken": "pk_...", "defaultListId": "...", "defaultAssignees": [123] } |

Tool: import_from_md

Parameters (conceptually):

• content: Full tasks.md string.
• list_id: Target list ID.
• parent_task_id: Parent task ID (sprints are created as subtasks under it).
• assignees: Optional array of ClickUp user IDs.
• custom_fields: Optional { id, value }[] for required or default fields.
• start_from_sprint: Optional: skip sprints below this number (default 1).
• mark_as_closed: Optional: mark created tasks closed after creation.

Markdown format: sprint headers like **Sprint 1 - Name**, then a table with columns including subtask title, description, estimated time, and real time (see clickup-mcp-cli guide).

Development

git clone <your-fork>
cd clickup-mcp-server
npm install
npm run build
npm run inspect

Testing import_from_md via MCP locally

Requires a real ClickUp token and IDs:

export CLICKUP_API_TOKEN=pk_...
export CLICKUP_TEST_LIST_ID=...
export CLICKUP_TEST_PARENT_TASK_ID=...
npm run test:mcp-import

This spawns the same stdio server as production and calls import_from_md through the MCP client.

License

MIT — see LICENSE.

Português (PT-BR)

Recursos

• MCP (stdio): Ferramentas para listas, tarefas, lançamentos de tempo, atualizações em lote e import_from_md (cria sprints e subtarefas a partir do conteúdo de um tasks.md).
• CLI: clickup-mcp-cli — descobrir metadados da lista, validar/importar/exportar Markdown, fechar tarefas, listar campos personalizados.
• Configuração: variável de ambiente ou arquivo .clickup-mcp.json.

Uso rápido com npx (servidor MCP)

Exemplo para Cursor ou outro host MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "clickup-markdown-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_seu_token"
      }
    }
  }
}

• npx -y clickup-markdown-mcp inicia o servidor MCP em stdio (entrada/saída padrão).
• Mantenha o token só em env ou em arquivo local ignorado pelo Git.

CLI com npx

O executável da CLI é clickup-mcp-cli:

npx -y -p clickup-markdown-mcp clickup-mcp-cli -- help
npx -y -p clickup-markdown-mcp clickup-mcp-cli discover --list <ID_DA_LISTA>
npx -y -p clickup-markdown-mcp clickup-mcp-cli validate caminho/tasks.md
npx -y -p clickup-markdown-mcp clickup-mcp-cli import caminho/tasks.md --parent <ID_TAREFA_PAI> --list <ID_DA_LISTA>

Configuração

| Método | Detalhes | |--------|----------| | Ambiente | CLICKUP_API_TOKEN (obrigatório). Opcional: CLICKUP_DEFAULT_LIST_ID, CLICKUP_DEFAULT_ASSIGNEES (IDs separados por vírgula). | | Arquivo | .clickup-mcp.json no diretório atual ou na pasta do usuário. Exemplo: { "apiToken": "pk_...", "defaultListId": "...", "defaultAssignees": [123] } |

Ferramenta import_from_md

Parâmetros principais:

• content: Texto completo do tasks.md.
• list_id: ID da lista onde as tarefas serão criadas.
• parent_task_id: ID da tarefa pai (cada sprint vira subtarefa desse pai).
• assignees: Opcional — IDs numéricos de usuários ClickUp.
• custom_fields: Opcional — lista de { id, value } para campos obrigatórios ou padrões.
• start_from_sprint: Opcional — ignorar sprints com número menor (padrão 1).
• mark_as_closed: Opcional — após criar, marcar como concluídas.

Formato Markdown: cabeçalhos **Sprint N - Nome** e tabela com título da subtarefa, descrição, tempo estimado e tempo real (use clickup-mcp-cli guide para o guia completo).

Publicação npm

O pacote é clickup-markdown-mcp porque o nome clickup-mcp-server já está registrado no npm por outro mantenedor.

Para publicar (mantenedor):

npm login
npm publish --access public

Teste local de import_from_md via MCP

Com token e IDs reais:

set CLICKUP_API_TOKEN=pk_...
set CLICKUP_TEST_LIST_ID=...
set CLICKUP_TEST_PARENT_TASK_ID=...
npm run test:mcp-import

No Linux/macOS, use export em vez de set.

Licença

MIT — veja LICENSE.