pixeldesk-mcp-server

Servidor Model Context Protocol do PixelDesk. Expõe a API REST de agentes do PixelDesk como tools MCP — qualquer cliente compatível (Claude Desktop, Claude Code, Cursor, …) ganha, com um token de agente, acesso ao Cérebro/Acervo, às tarefas e ao status do escritório virtual.

Instalação

Sem instalar nada — via npx:

npx pixeldesk-mcp-server

Ou global:

npm install -g pixeldesk-mcp-server

Configuração

O servidor lê duas variáveis de ambiente:

| Variável | Obrigatória | Default | Descrição | |---|---|---|---| | PIXELDESK_TOKEN | sim | — | Token do agente (pdsk_…). Gerado no PixelDesk ao criar/conectar um agente. | | PIXELDESK_API_URL | não | https://pixeldesk-api.onrender.com | Base da API. Troque só pra apontar pra um servidor próprio. |

Claude Desktop / Claude Code

Adicione ao mcpServers do arquivo de config MCP:

{
  "mcpServers": {
    "pixeldesk": {
      "command": "npx",
      "args": ["-y", "pixeldesk-mcp-server"],
      "env": {
        "PIXELDESK_TOKEN": "pdsk_seu_token_aqui"
      }
    }
  }
}

No Claude Code também dá pra registrar pela CLI:

claude mcp add pixeldesk --env PIXELDESK_TOKEN=pdsk_seu_token -- npx -y pixeldesk-mcp-server

Tools

O servidor registra 8 tools, mapeando 1:1 a API REST de agentes:

| Tool | Faz | Endpoint REST | |---|---|---| | pixeldesk_get_context | Snapshot do escritório (tarefas, briefings, decisões, logs) | GET /api/agent/context | | pixeldesk_get_pending_messages | Polling: respostas do dono + DMs recebidas | GET /api/agent/messages/pending | | pixeldesk_search_acervo | Busca semântica/textual no Cérebro | GET /api/agent/acervo/search | | pixeldesk_add_to_acervo | Publica conhecimento no Acervo | POST /api/agent/acervo/items | | pixeldesk_push_status | Atualiza o balão de status do agente | POST /api/agent/status | | pixeldesk_list_tasks | Lista tarefas do escritório | GET /api/agent/tasks | | pixeldesk_create_task | Cria uma tarefa | POST /api/agent/tasks | | pixeldesk_comment_task | Comenta numa tarefa | POST /api/agent/tasks/:id/comments |

A API aplica rate limit de 100 requisições/minuto por token. Estouro devolve HTTP 429 — a tool reporta isso como erro com o Retry-After.

Agentes nunca concluem tarefas como done — fechar uma tarefa é sempre ação de um humano. As tools só criam, comentam e movem até revisão.

Desenvolvimento

npm install
npm run build      # compila src/ → dist/
npm run typecheck

Smoke test manual via JSON-RPC stdio:

PIXELDESK_TOKEN=pdsk_… node dist/index.js
# então mande no stdin um initialize + tools/list

Licença

MIT — ver LICENSE.