# kinbox-mcp

MCP Server para integração com a [API Kinbox](https://docs.kinbox.com.br) — atendimento via WhatsApp, Instagram e outros canais.

## Ferramentas disponíveis

| Categoria | Tools |
|---|---|
| Contatos | `kinbox_list_contacts`, `kinbox_get_contact`, `kinbox_create_contact`, `kinbox_update_contact` |
| Sessões | `kinbox_list_sessions`, `kinbox_get_session` |
| Tags | `kinbox_list_tags`, `kinbox_add_tag`, `kinbox_remove_tag`, `kinbox_create_tag` |
| Campanhas | `kinbox_list_campaigns`, `kinbox_get_campaign`, `kinbox_create_campaign`, `kinbox_send_campaign`, `kinbox_cancel_campaign` |
| Deals (CRM) | `kinbox_list_deals`, `kinbox_get_deal`, `kinbox_create_deal`, `kinbox_update_deal` |
| Pipelines | `kinbox_list_pipelines`, `kinbox_get_pipeline` |
| Produtos | `kinbox_list_products`, `kinbox_get_product` |
| Campos personalizados | `kinbox_list_custom_fields` |
| Envio de mensagem | `kinbox_send_message` |
| Escape hatch | `kinbox_raw_request` |

## Configuração

### 1. Instalar dependências

```bash
npm install
```

### 2. Obter API Key

No Kinbox: **Configurações → Integrações → API** → criar token.

### 3. Configurar variável de ambiente

```bash
export KINBOX_API_KEY=kb_live_seu_token_aqui
```

### 4. Adicionar ao Claude Code

Copie `.mcp.json` para a raiz do seu projeto (ou `~/.claude/mcp.json` para global) e defina `KINBOX_API_KEY` no ambiente:

```json
{
  "mcpServers": {
    "kinbox": {
      "type": "stdio",
      "command": "node",
      "args": ["/caminho/para/kinbox-mcp.js"],
      "env": {
        "KINBOX_API_KEY": "kb_live_seu_token"
      }
    }
  }
}
```

## Notas de integração

Conhecimento acumulado sobre a plataforma (webhook inbound, payload ideal para
cenários, nó "Buscar contato", canais oficial × não-oficial, API v3 de workflows/logs,
doc oficial) em [`NOTAS-INTEGRACAO.md`](./NOTAS-INTEGRACAO.md).

## n8n — recriar a API como HTTP nodes

[`N8N-HTTP-NODES.md`](./N8N-HTTP-NODES.md) lista os **315 endpoints** da API
(de `docs/openapi-oficial.json`) com método, rota, params e campos de body, mais
instruções para um agente criar **um HTTP Request node por endpoint** no n8n.
Spec completo da doc oficial em [`docs/openapi-oficial.json`](./docs/openapi-oficial.json).

## Base URL

`https://api4.kinbox.com.br` (API v1)

## Dependências

- Node.js 18+
- `@modelcontextprotocol/sdk`
- `zod`