callcenter-kpi-mcp
Runs read-only, parameterized SQL queries against a PostgreSQL call center database (materialized views) to answer KPI questions: average wait/handling time (TME/TMA) per period, CSAT by operator, repeat contacts, abandonment rate, hourly/weekday volume heatmaps, operator rankings, volume forecasts, and company comparisons, plus listing available companies and queues with data coverage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@callcenter-kpi-mcp Qual operador teve mais rechamadas na semana passada?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Pergunta: "Qual operador teve mais rechamadas semana passada?"
O modelo chama
rechamadascom 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| UStack: TypeScript (strict) · Node 22 · MCP SDK · PostgreSQL 17 · Zod · Vitest + Testcontainers · Docker Compose · GitHub Actions
Ferramentas
Ferramenta | Responde |
| Quais empresas e filas existem, e de que dia a que dia há dados |
| Tempo médio de espera e de atendimento por dia, semana ou total |
| Mapa de calor: média de atendimentos por dia da semana e hora, e o pico |
| Nota média e % de satisfeitos por operador, com mínimo de respostas |
| Quantos clientes voltaram dentro da janela, por operador, fila ou empresa |
| Ranking por volume, TMA, TME ou CSAT |
| Volume dos próximos dias pela média do mesmo dia da semana |
| Um atendimento e os outros contatos do mesmo cliente na semana |
| Abandono por fila, hora, dia ou empresa |
| 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 buildO 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.jsComandos
Comando | Faz |
| Recria os dados fictícios (usa |
| Servidor direto do TypeScript |
| Testes (sobem um Postgres descartável no Docker) |
| 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 comdefault_transaction_read_onlye 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_operadorguarda 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 toolsatendimento_detalheDetalhe de um atendimentoARead-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 empresasARead-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 operadorARead-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ívelARead-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 volumeARead-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 operadoresARead-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.
rechamadasRechamadasARead-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 abandonoBRead-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íodoARead-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 volumeARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with PostgreSQL databases using natural language queries, providing secure read-only access to database schemas and SQL translation capabilities.69 npmISC
- AlicenseAqualityDmaintenanceEnables 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.15MIT
- AlicenseNot gradedqualityCmaintenanceGives 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
- AlicenseAqualityBmaintenanceEnables 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.7MIT