zerosync-mcp

Servidor MCP (stdio) que expõe as ações do ZeroSync como ferramentas para assistentes de IA (Claude Desktop, n8n, código próprio, etc.).

Ele é um wrapper fino sobre a API REST pública v1 do ZeroSync (https://app.zerosync.com.br/api/v1), autenticado por um Personal Access Token (PAT). O servidor não acessa o banco diretamente — todo o isolamento por usuário é garantido pela própria API.

Ferramentas disponíveis

| Tool | O que faz | Endpoint v1 | | --- | --- | --- | | criar_tarefa | Cria tarefa/compromisso na agenda | POST /tasks | | listar_agenda | Lista tarefas de um dia | GET /tasks | | lancar_despesa | Lança uma despesa | POST /transactions (type=expense) | | lancar_receita | Lança uma receita | POST /transactions (type=income) | | resumo_financeiro | Resumo do mês (entradas/saídas/saldo) | GET /finance/summary | | marcar_habito | Marca um hábito como feito | POST /habits/log | | listar_habitos | Lista hábitos e status do dia | GET /habits | | add_compra | Adiciona item à lista de compras | POST /shopping | | criar_objetivo | Cria um objetivo/meta | POST /goals | | add_nota | Adiciona nota de diário | POST /notes | | anotar_tarefa | Anota um afazer no backlog (sem horário) | POST /todos | | listar_tarefas | Lista afazeres pendentes agrupados | GET /todos | | concluir_tarefa | Conclui um afazer por título | POST /todos/complete |

Cada ferramenta retorna o texto de resumo (summary) devolvido pela API.

Pré-requisitos

• Node.js 18+ (testado em 20/22/24; usa o fetch global).
• Um Personal Access Token do ZeroSync. Gere em https://app.zerosync.com.br (seção de API/tokens).

Variáveis de ambiente

| Variável | Obrigatória | Default | Descrição | | --- | --- | --- | --- | | ZEROSYNC_API_KEY | Sim | — | Seu Personal Access Token (PAT). | | ZEROSYNC_API_URL | Não | https://app.zerosync.com.br/api/v1 | Base da API v1 (útil para apontar para um ambiente local/staging). |

Se ZEROSYNC_API_KEY não estiver definida, o servidor encerra com uma mensagem clara.

Instalação e build

cd packages/zerosync-mcp
npm install
npm run build   # compila TypeScript para dist/

Para desenvolvimento sem build, use npm run dev (executa via tsx).

Conectar no Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione o servidor em mcpServers. A forma recomendada é via npx (quando o pacote estiver publicado no npm):

{
  "mcpServers": {
    "zerosync": {
      "command": "npx",
      "args": ["-y", "zerosync-mcp"],
      "env": {
        "ZEROSYNC_API_KEY": "seu_personal_access_token_aqui"
      }
    }
  }
}

Rodando a partir do código local (sem publicar no npm)

Aponte diretamente para o dist/index.js gerado pelo build:

{
  "mcpServers": {
    "zerosync": {
      "command": "node",
      "args": ["C:\\Users\\voce\\Apps\\ZeroSync\\packages\\zerosync-mcp\\dist\\index.js"],
      "env": {
        "ZEROSYNC_API_KEY": "seu_personal_access_token_aqui"
      }
    }
  }
}

Para apontar para um ambiente local da API, adicione "ZEROSYNC_API_URL": "http://localhost:3000/api/v1" ao bloco env.

Depois de salvar, reinicie o Claude Desktop. As ferramentas criar_tarefa, lancar_despesa, etc. ficarão disponíveis.

Usar com n8n / código próprio

Qualquer cliente MCP que fale stdio funciona. Inicie o processo com a env definida:

ZEROSYNC_API_KEY=seu_token npx -y zerosync-mcp
# ou, a partir do build local:
ZEROSYNC_API_KEY=seu_token node dist/index.js

No Windows (PowerShell):

$env:ZEROSYNC_API_KEY = "seu_token"; node dist/index.js

Erros comuns

| Mensagem | Causa | Solução | | --- | --- | --- | | ZEROSYNC_API_KEY não definida | Env ausente | Defina a variável com seu PAT. | | Token inválido ou revogado | Token errado/revogado | Gere um novo PAT no ZeroSync. | | Seu token não tem permissão (escopo) | PAT sem o escopo necessário (read/write) | Gere um token com o escopo adequado. | | Não consegui falar com o ZeroSync | Rede/URL incorreta | Verifique conexão e ZEROSYNC_API_URL. |