BePlus MCP

Servidor MCP da equipe BePlus que dá ao Claude Code / Claude Desktop / Cursor acesso à sua conta da plataforma para gerar mídia (imagens, vídeos e áudio) e consultar dados (calls gravadas/transcritas, projetos e clientes) — tudo passando pela sua conta.

Diferente de chamar Gemini/BytePlus direto, toda ação roteia pelo backend da BePlus e herda automaticamente: débito de diamantes, limites por usuário, visibilidade da equipe e histórico/monitoramento no admin. A chave do provider nunca toca a sua máquina.

Como funciona

Claude Code/Desktop/Cursor  ──stdio──▶  beplus-mcp  ──HTTPS (Bearer pat_…)──▶  BePlus /api/v1/mcp

Você se autentica com um Personal Access Token (PAT) gerado no painel da BePlus. O MCP só age em nome da SUA conta.

1. Gere um Personal Access Token

No app da BePlus → Configurações da conta → Tokens de acesso → Criar token. Copie o token (pat_…) — ele só aparece uma vez.

2. Configure no seu cliente

Claude Code (CLI)

claude mcp add beplus \
  --env BEPLUS_API_TOKEN=pat_seu_token \
  --env BEPLUS_API_URL=https://api.beplus.academy \
  -- npx -y beplus-mcp

Claude Desktop (claude_desktop_config.json) / Cursor (.cursor/mcp.json)

macOS / Linux:

{
  "mcpServers": {
    "beplus": {
      "command": "npx",
      "args": ["-y", "beplus-mcp"],
      "env": {
        "BEPLUS_API_URL": "https://api.beplus.academy",
        "BEPLUS_API_TOKEN": "pat_seu_token"
      }
    }
  }
}

Windows — o npx precisa do wrapper cmd /c (senão o servidor não inicia):

{
  "mcpServers": {
    "beplus": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "beplus-mcp"],
      "env": {
        "BEPLUS_API_URL": "https://api.beplus.academy",
        "BEPLUS_API_TOKEN": "pat_seu_token"
      }
    }
  }
}

Caminho do config (Claude Desktop): macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json.

Reinicie o cliente. Rode a tool whoami para confirmar o vínculo.

Variáveis de ambiente

| Var | Obrigatória | Default | Descrição | |-----|-------------|---------|-----------| | BEPLUS_API_TOKEN | ✅ | — | Seu Personal Access Token (pat_…). | | BEPLUS_API_URL | — | https://api.beplus.academy | Origem da API BePlus. | | BEPLUS_INLINE_IMAGES | — | 1 | 0 desativa imagens inline (só URLs). | | BEPLUS_VERIFY_ON_START | — | 0 | 1 valida o token no startup e loga a conta (stderr). | | BEPLUS_COST_WARN_THRESHOLD | — | — | Avisa quando o custo passa de N 💎. | | BEPLUS_ACTIVE_PROJECT | — | — | Projeto ativo padrão da sessão (uuid ou code). |

Tools

Geração de mídia

| Tool | O que faz | |------|-----------| | generate_image | Gera imagem (nano-banana / gpt-image-2). Bloqueante ~90s; retorna URL + imagem inline. Suporta refs, tamanho/qualidade, e extras do gpt-image-2 (background, moderation, output_format/compression). | | generate_video | Gera vídeo (Seedance / Kling). Aguarda ~120s; senão devolve o id pra check_generation. Suporta first/last frame, refs de imagem/vídeo/áudio, prompt negativo, áudio gerado, mode e motion-control. | | generate_audio | Sintetiza fala (Gemini TTS, ~30 vozes, multi-locutor). Síncrono. | | generate_music | Gera música completa (Suno v5.5 / v4.5) — modo descrição ou letra própria, tags, instrumental, vocal_gender, controles criativos. Async. | | check_generation | Status de uma geração async por id. | | cancel_generation | Cancela uma geração em fila/processamento (estorna diamantes). | | estimate_cost | Custo em diamantes antes de gerar. | | read_image_metadata / analyze_media | Lê a proveniência embutida numa imagem / analisa mídia (imagem/vídeo/áudio/PDF) com prompt. |

Referências de arquivo local (desde 0.8.1): os campos de mídia — reference_images, first_frame_image, last_frame_image, reference_videos, reference_audios, motion_video (geração) e media_urls (analyze_media) — aceitam URL pública OU caminho de arquivo local (/caminho/foto.png, ~/Desktop/ref.jpg, file://…). Caminhos locais sobem automaticamente pro R2 da BePlus e viram URL pública antes de chegar ao provider — não precisa mais hospedar a imagem você mesmo.

Calls (reuniões gravadas e transcritas)

| Tool | O que faz | |------|-----------| | search_calls | Busca nas calls visíveis (suas, da equipe, compartilhadas). Filtros: query, project, client, visibility, speaker. | | get_call | Conteúdo completo de uma call por id: resumo, falantes, projeto/cliente, mídia e a transcrição inteira. |

Projetos / Clientes / Conta

| Tool | O que faz | |------|-----------| | list_projects · create_project · set_active_project | Lista/cria projetos e define o ativo (mesma fonte da web). | | list_clients · create_client · set_active_client | Clientes/marcas (container acima dos projetos). | | list_models | Modelos disponíveis + preços + limites (fonte de verdade em runtime). | | get_balance | Saldo de diamantes. | | whoami | Conta vinculada (link check do PAT). |

Toda geração mostra Custo: N 💎 · Saldo: M 💎. As tools de calls e listagem respeitam a visibilidade da equipe — só retornam o que a sua conta pode ver.

Desenvolvimento

npm install
npm run typecheck
npm run build      # gera dist/index.js (bin)
npm run dev        # roda via tsx

# Smoke-test com o MCP Inspector:
BEPLUS_API_TOKEN=pat_… npx @modelcontextprotocol/inspector node dist/index.js

Notas

• stdout é o canal JSON-RPC — todo log vai pra stderr e o token nunca é logado.
• Limites, créditos, visibilidade e logging são enforçados pelo backend; um PAT vazado é limitado aos caps/diamantes do dono e pode ser revogado no painel.
• list_models é a fonte de verdade em runtime; os enums do pacote podem ficar atrás quando o backend adiciona modelos.