Skip to main content
Glama
callcenter-kpi-mcp

callcenter-kpi-mcp

by jojao115

callcenter-kpi-mcp

Servidor MCP que deixa um LLM (Claude, ChatGPT, Cursor) consultar os indicadores de um call center em linguagem natural: TME, TMA, CSAT, rechamadas, abandono, mapa de calor e previsão de volume.

CI TypeScript Licença MIT

Pergunta: "Qual operador teve mais rechamadas semana passada?"

O modelo chama rechamadas com o período da semana, o servidor roda uma consulta parametrizada no Postgres e o modelo responde com os números: quem atendeu, quantos clientes voltaram em 24 h e a taxa de cada um.

O problema

Supervisor de call center vive de indicador: espera na fila, nota do cliente, quem resolve de primeira, que horário precisa de mais gente. Esses números ficam num banco que só quem sabe SQL consulta, ou num painel que responde só às perguntas que alguém pensou antes.

Com MCP, o supervisor pergunta do jeito que fala, e o modelo escolhe a ferramenta certa. Cada ferramenta é uma consulta revisada, com entrada validada e só leitura: o modelo nunca escreve SQL.

Related MCP server: Postgres MCP Pro

Como funciona

flowchart LR
    U[Supervisor] -->|pergunta| L[LLM<br/>Claude, Cursor...]
    L -->|chama ferramenta<br/>JSON validado por Zod| S[callcenter-kpi-mcp<br/>stdio]
    S -->|SQL parametrizado<br/>usuário só de leitura| P[(PostgreSQL<br/>views materializadas)]
    P --> S --> L -->|resposta com números| U

Stack: TypeScript (strict) · Node 22 · MCP SDK · PostgreSQL 17 · Zod · Vitest + Testcontainers · Docker Compose · GitHub Actions

Ferramentas

Ferramenta

Responde

listar_empresas

Quais empresas e filas existem, e de que dia a que dia há dados

tme_por_periodo

Tempo médio de espera e de atendimento por dia, semana ou total

volume_por_hora

Mapa de calor: média de atendimentos por dia da semana e hora, e o pico

csat_por_operador

Nota média e % de satisfeitos por operador, com mínimo de respostas

rechamadas

Quantos clientes voltaram dentro da janela, por operador, fila ou empresa

ranking_operadores

Ranking por volume, TMA, TME ou CSAT

previsao_volume

Volume dos próximos dias pela média do mesmo dia da semana

atendimento_detalhe

Um atendimento e os outros contatos do mesmo cliente na semana

taxa_abandono

Abandono por fila, hora, dia ou empresa

comparar_empresas

As empresas lado a lado nos principais indicadores

Toda resposta traz o período consultado e a definição do indicador, para o modelo não inventar o que é "TME".

Rodar localmente

Precisa de Node 22 e Docker.

git clone https://github.com/jojao115/callcenter-kpi-mcp.git
cd callcenter-kpi-mcp
cp .env.example .env
docker compose run --rm --build seed   # sobe o Postgres e carrega ~53 mil atendimentos fictícios
npm install && npm run build

O comando sobe o banco em segundo plano, roda o seed e devolve o terminal; o banco continua no ar (docker compose down para parar). O servidor MCP roda por stdio: quem inicia é o cliente. No Claude Desktop, em claude_desktop_config.json:

{
  "mcpServers": {
    "callcenter-kpi": {
      "command": "node",
      "args": ["C:/caminho/para/callcenter-kpi-mcp/dist/main.js"],
      "env": {
        "DATABASE_URL": "postgres://mcp_leitura:leitura_dev@localhost:5433/callcenter"
      }
    }
  }
}

Para testar sem cliente nenhum, use o inspetor oficial:

npx @modelcontextprotocol/inspector node dist/main.js

Comandos

Comando

Faz

npm run seed

Recria os dados fictícios (usa SEED_DATABASE_URL)

npm run dev

Servidor direto do TypeScript

npm test

Testes (sobem um Postgres descartável no Docker)

npm run lint / npm run typecheck

ESLint e checagem de tipos

Sem Docker, os testes rodam contra qualquer Postgres descartável: TEST_PG_URL=postgres://usuario:senha@localhost:5432/postgres npm test.

Decisões técnicas

  • Ferramentas fechadas em vez de text-to-SQL. Deixar o LLM escrever SQL é a demo mais rápida e o pior risco: consulta errada que parece certa, tabela inteira no contexto, porta aberta para injeção. Aqui cada pergunta comum vira uma ferramenta com consulta revisada e testada. Partes variáveis do SQL (agrupar por, ordenar por) saem de um mapa fixo escolhido por enum; valores sempre vão como parâmetro.

  • Três camadas de só leitura. Usuário do Postgres só com SELECT, sessão com default_transaction_read_only e tempo máximo por consulta. Tem teste que tenta apagar a tabela pelo pool do servidor e confere que o banco recusa.

  • Views materializadas com somas, não médias. mv_dia_operador guarda soma de espera e contagem de atendidos por dia e operador. A média de um mês sai da soma das somas, e não da média das médias, que dá peso igual a um dia de 10 e a um de 500 atendimentos.

  • Fuso explícito. Todo agrupamento por dia ou hora usa America/Sao_Paulo. Um atendimento às 23h30 cai no dia certo, e há teste para isso.

  • Seed determinístico. Gerador com semente fixa (mulberry32): mesma semente e mesma data final (SEED_DATA_FIM), os mesmos ~53 mil atendimentos. Os dados seguem padrões de operação (pico de manhã, segunda cheia, abandono que cresce com a espera, cliente que volta depois de nota baixa), para as perguntas terem resposta interessante.

  • Testes contra Postgres de verdade. Uma base pequena montada à mão confere cada número de cabeça; outra, gerada, passa por todas as ferramentas pelo protocolo MCP. Cada arquivo de teste usa um banco clonado de um modelo, então rodam em paralelo.

Resultado no projeto real

Versão pública, com dados fictícios, de uma plataforma de indicadores que uso em produção com 8 provedores de internet e cerca de 4 mil atendimentos por semana.

Próximos passos

  • Transporte HTTP (Streamable HTTP) com autenticação por token, para rodar como serviço

  • Deploy do banco e do servidor no Railway ou Fly.io, com um cliente de demonstração

  • Previsão com tendência e feriados, comparada com a média simples num backtest

Licença

MIT. Os dados são gerados por script; nenhuma empresa, pessoa ou atendimento é real.

Available Tools

10 tools
atendimento_detalheDetalhe de um atendimentoA
Read-only

Mostra um atendimento pelo id: empresa, fila, operador, canal, motivo, horários, espera, duração e nota, e os contatos do mesmo cliente nos 7 dias antes e depois.

Inputs: id (required).

comparar_empresasComparar empresasA
Read-only

Põe as empresas lado a lado num período: volume, taxa de abandono, TME, TMA, CSAT médio e % de satisfeitos.

Inputs: data_fim, data_inicio.

csat_por_operadorCSAT por operadorA
Read-only

Nota média de satisfação (CSAT, 1 a 5) e % de satisfeitos por operador num período. Ignora quem teve poucas respostas, para a média não enganar.

Inputs: ordem, limite, fila_id, data_fim, +3 more.

listar_empresasEmpresas, filas e período disponívelA
Read-only

Lista as empresas atendidas, as filas de cada uma (com ids), quantos operadores ativos há e o primeiro e o último dia com dados. Chame primeiro para descobrir ids e datas válidas.

Inputs: no named parameters.

previsao_volumePrevisão de volumeA
Read-only

Prevê o volume de atendimentos dos próximos dias pela média das últimas semanas no mesmo dia da semana (média móvel simples), a partir do último dia com dados. Mostra o mínimo e o máximo do histórico usado, para dar a ideia da variação.

Inputs: fila_id, empresa_id, dias_a_frente, semanas_historico.

ranking_operadoresRanking de operadoresA
Read-only

Ranking de operadores por volume atendido, TMA, TME ou CSAT, com os quatro números de cada um. Ordem desc = do maior para o menor (para "mais rápido" em TMA use asc).

Inputs: ordem, limite, fila_id, data_fim, +3 more.

rechamadasRechamadasA
Read-only

Quantos atendimentos finalizados tiveram rechamada: o mesmo cliente voltou a abrir atendimento dentro da janela de horas. Rechamada alta indica problema não resolvido. Agrupa por operador (quem atendeu o primeiro contato), fila ou empresa, do maior número para o menor.

Inputs: limite, fila_id, data_fim, empresa_id, +3 more.

taxa_abandonoTaxa de abandonoB
Read-only

Volume, abandonos e taxa de abandono (% de clientes que desistiram na fila) por fila, hora do dia, dia ou empresa.

Inputs: fila_id, data_fim, empresa_id, agrupar_por, +1 more.

tme_por_periodoTME e TMA por períodoA
Read-only

Tempo médio de espera (TME) e tempo médio de atendimento (TMA) num período, por dia, por semana (começando na segunda) ou no total. Filtra por empresa e por fila.

Inputs: fila_id, data_fim, empresa_id, agrupar_por, +1 more.

volume_por_horaMapa de calor de volumeA
Read-only

Média de atendimentos abertos por dia da semana e hora do dia (mapa de calor), e o horário de pico. Serve para dimensionar escala. Filtra por empresa e por fila.

Inputs: fila_id, data_fim, empresa_id, data_inicio.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool targets a distinct KPI or dimension: TME/TMA, volume heatmap, CSAT per operator, abandonment, repeat calls, ranking, forecast, and single-ticket detail are clearly separated. There is some overlap because comparar_empresas and ranking_operadores re-surface TME/TMA/CSAT already produced by tme_por_periodo and csat_por_operador, but their aggregation focus (cross-company comparison vs. per-operator ranking) is stated clearly enough to choose correctly.

    Naming Consistency4/5

    All names are lowercase snake_case in Portuguese with a dominant metric_by_dimension pattern (tme_por_periodo, volume_por_hora, csat_por_operador, taxa_abandono). Two discovery tools use verb_noun (listar_empresas, comparar_empresas) and a few are bare noun phrases (rechamadas, previsao_volume, ranking_operadores, atendimento_detalhe), which is a minor deviation but still readable and predictable.

    Tool Count5/5

    Ten tools is a well-scoped surface for a call-center KPI analytics server, with each tool covering a distinct analytical need. No filler or redundant tools are present, and no capability feels crammed into an unrelated tool.

    Completeness4/5

    The surface covers discovery (companies/queues/operators/date range), core metrics (TME, TMA, volume, CSAT, abandonment), diagnostics (repeat calls, ticket detail), and forward-looking planning (forecast). Notable gaps remain around service-level/SLA (e.g. % answered within N seconds), transfers, and agent occupancy, which agents would need for a full operational picture.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with PostgreSQL databases using natural language queries, providing secure read-only access to database schemas and SQL translation capabilities.
      6
      9 npm
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to analyze, optimize, and safely interact with PostgreSQL databases, including health checks, index recommendations, query planning, and SQL execution with read-only and production protection modes.
      15
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives an LLM read-only, schema-aware SQL database access so users can ask business questions in plain English and receive the exact result set, with malformed queries returned as errors for automatic retry and correction.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM agents to read PostgreSQL data through a fixed catalog of parameterized, read-only queries, without allowing free-form SQL or access outside bounded inputs.
      7
      MIT