Kalodata MCP Server (TikTok Shop Analytics)

Servidor MCP (Model Context Protocol) construído em Python com o SDK oficial (FastMCP v1.x). Funciona como um wrapper completo para a Kalodata Open API, permitindo que assistentes e agentes de IA (como Perplexity AI, Claude, Cursor e outros) realizem pesquisas aprofundadas de mercado, análise de nichos, produtos vencedores, criadores e vídeos virais do TikTok Shop.

📌 O que é este projeto?

Este servidor expõe 8 ferramentas MCP para consulta de dados do TikTok Shop:

1. category_rank — Ranking de categorias por receita.

2. category_detail — Detalhes completos de uma categoria.

3. product_rank — Ranking dos produtos mais vendidos.

4. product_detail — Detalhes e métricas de um produto.

5. creator_rank — Ranking de criadores/influenciadores.

6. creator_detail — Detalhes e performance de um criador.

7. video_rank — Ranking de vídeos virais de vendas.

8. video_detail — Métricas de um vídeo específico.

Transporte nativo: Streamable HTTP na rota /mcp, compatível com Perplexity AI Custom Remote Connectors.

Related MCP server: TikTok Complete MCP Server

🚀 Setup Local

1. Pré-requisitos

• Python 3.10 ou superior.

• Chave de API Kalodata (KALODATA_SECRET_KEY).

2. Ambiente Virtual e Dependências

python -m venv .venv

# Ativar (Windows PowerShell):
.venv\Scripts\Activate.ps1
# Ativar (Linux/macOS):
source .venv/bin/activate

pip install -r requirements.txt

3. Configurar .env

cp .env.example .env

Edite .env:

KALODATA_SECRET_KEY=sua_chave_aqui
KALODATA_BASE_URL=https://staging.kalodata.com
PORT=8000
HOST=0.0.0.0

Nota: Se sua chave for de produção, altere KALODATA_BASE_URL para o host fornecido no e-mail de ativação da Kalodata.

🧪 Testes e Validação Local

1. Testar conexão direta com a API Kalodata (sem MCP)

python test_local.py

2. Iniciar o servidor MCP

python server.py

Saída esperada nos logs:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
[kalodata-mcp] Servidor iniciando em http://0.0.0.0:8000/mcp
[kalodata-mcp] Transporte: streamable-http | 8 ferramentas registradas

3. Testar o endpoint /mcp via linha de comando

O endpoint correto é /mcp (testado e confirmado localmente com HTTP 200).

Windows (PowerShell):

Invoke-WebRequest -Uri http://localhost:8000/mcp `
  -Method POST `
  -Headers @{"Accept"="application/json, text/event-stream"; "Content-Type"="application/json"} `
  -Body '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' `
  -UseBasicParsing | Select-Object -ExpandProperty Content

Linux/macOS (curl):

curl -s -N \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  http://localhost:8000/mcp

Resposta esperada:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"kalodata","version":"1.29.1"},...}}

Importante: O Streamable HTTP exige os dois headers Accept: application/json, text/event-stream. Sem eles, o servidor retorna 406 Not Acceptable (comportamento correto do protocolo).

4. Testar com MCP Inspector (interface visual)

npx @modelcontextprotocol/inspector python server.py

🌐 Deploy Remoto (Render.com)

O projeto já inclui o arquivo render.yaml na raiz, permitindo deploy via Blueprint no Render.

Passo a Passo:

1. Criar repositório no GitHub e fazer push:

   git remote add origin https://github.com/seu-usuario/kalodata-mcp.git
   git push -u origin master

2. Acesse dashboard.render.com → New + → Blueprint.

3. Conecte o repositório. O Render detecta o render.yaml automaticamente.

4. Configure as variáveis de ambiente manualmente no painel do Render:

   • KALODATA_SECRET_KEY: sua chave da Kalodata (rotacionada/nova)

   • KALODATA_BASE_URL: https://staging.kalodata.com (ou URL de produção)

5. Clique em Apply. O Render fará o build e gerará a URL pública (ex: https://kalodata-mcp.onrender.com).

6. Teste o deploy:

   curl -s -N \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
     https://kalodata-mcp.onrender.com/mcp

🔗 Registrando no Perplexity AI

1. Acesse Perplexity AI → Configurações da Conta → Conectores.

2. Clique em "+ Conector personalizado".

3. Preencha:

   • Nome: Kalodata TikTok Shop Analytics

   • Tipo: Remoto

   • URL: https://kalodata-mcp.onrender.com/mcp

   • Transporte: Streamable HTTP

   • Autenticação: Nenhuma

4. Salve. O Perplexity descobrirá automaticamente as 8 ferramentas.

Por que "Nenhuma" autenticação? A chave da Kalodata fica no servidor (variável de ambiente), nunca exposta ao Perplexity.

✅ Checklist de Deploy Manual (Tarefas Fora do Agente)

Estas etapas dependem de contas externas e devem ser executadas por você manualmente:

• 1. GitHub — Criar repositório kalodata-mcp no GitHub (pode ser privado).

• 2. Git Push — Rodar git remote add origin <URL> e git push -u origin master.

• 3. Render — Criar conta em render.com se ainda não tiver.

• 4. Blueprint — No Render: New + → Blueprint → conectar repositório → detecta render.yaml automaticamente.

• 5. Variáveis secretas — No painel do Render, preencher KALODATA_SECRET_KEY e KALODATA_BASE_URL manualmente (nunca commite esses valores).

• 6. Aguardar deploy — O Render executa pip install -r requirements.txt e python server.py. Aguardar status "Live".

• 7. Testar endpoint público — Copiar a URL gerada (ex: https://kalodata-mcp.onrender.com) e testar o endpoint /mcp com curl.

• 8. Perplexity — Ir em Configurações → Conectores → + Conector personalizado → Remoto → colar https://<url>/mcp → Streamable HTTP → Autenticação: Nenhuma.

🔒 Aviso de Segurança

• NUNCA comite o arquivo .env com chave real. O .gitignore já o ignora.

• NUNCA adicione a chave dentro do render.yaml — as variáveis sync: false são inseridas manualmente no dashboard do Render.

• A chave da Kalodata vive apenas na variável de ambiente do servidor, nunca exposta ao cliente MCP.