HSV4 MCP Server

Acesso ao V4 Health Score direto pelo Claude: consultar clientes, preencher semanas e acompanhar a saúde da carteira da sua unidade.

Status

Este pacote ainda não foi publicado no npm. Os comandos de instalação abaixo funcionarão somente após o comando npm publish ser executado. Enquanto isso, use o arquivo .mcpb fornecido.

Instalação

Claude Code (uma linha)

claude mcp add hsv4 --env HSV4_EMAIL=seu@email --env HSV4_TOKEN=seu-token -- npx -y hsv4-mcp

Substitua:

• seu@email — seu email cadastrado no HSV4
• seu-token — seu token pessoal (veja abaixo como gerar)

Claude Desktop

Edite o arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS ou %APPDATA%\Claude\claude_desktop_config.json no Windows) e adicione a seção mcpServers:

{
  "mcpServers": {
    "hsv4": {
      "command": "npx",
      "args": ["-y", "hsv4-mcp"],
      "env": {
        "HSV4_EMAIL": "seu@email",
        "HSV4_TOKEN": "seu-token"
      }
    }
  }
}

Substitua os valores de HSV4_EMAIL e HSV4_TOKEN com suas credenciais reais.

Como Pegar Meu Token

1. Acesse o V4 Health Score pelo navegador
2. Vá no menu de Acesso MCP (ou Configurações > Integração)
3. Clique no botão Gerar Token Pessoal
4. Copie o token exibido e guarde em um lugar seguro

O token nunca é exibido novamente — se perder, gere um novo.

Deu Errado?

"Command not found: claude"

Você não tem o Claude Code CLI instalado. Instale com:

npm install -g @anthropic-ai/claude-code

"Invalid token" ou "Unauthorized"

• Confirme que o token foi copiado completamente (sem espaços antes ou depois)
• Verifique se o email está exatamente igual ao cadastrado no HSV4
• Tente gerar um novo token no HSV4 e usar o novo

"Node version X is not supported"

O servidor precisa de Node 18 ou mais novo. Verifique sua versão com node --version e atualize se necessário.

"Cannot find module ../index.cjs"

A instalação pode estar corrompida. Tente reinstalar com:

# Claude Code
claude mcp remove hsv4
claude mcp add hsv4 --env HSV4_EMAIL=seu@email --env HSV4_TOKEN=seu-token -- npx -y hsv4-mcp

Ferramentas Disponíveis

O servidor fornece acesso a:

• autenticar — testa sua conexão com o HSV4
• listar_clientes — lista clientes da sua unidade
• criar_cliente — adiciona um novo cliente
• editar_cliente — atualiza dados de um cliente
• preencher_semana — registra health score da semana
• listar_historico — histórico completo de um cliente
• importar_csv — importa clientes em lote
• E mais...

Use @hsv4 no Claude para chamar qualquer uma delas.

Suporte

Problemas? Entre em contato com o time de suporte do V4 Health Score.