MCP Cost Tracker Router

Consciência de custos em tempo real para fluxos de trabalho de agentes MCP — acompanhe gastos, defina orçamentos e roteie por precificação de modelo.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Cost Tracker & Router

Pacote npm mcp-cost-tracker-router

Consciência de custos local-first para fluxos de trabalho de agentes MCP. A contagem de tokens é calculada offline usando js-tiktoken — sem proxy, sem ida e volta de API, sem dados de gastos saindo da sua máquina. Quando os custos aumentam, sugestões de roteamento apontam para modelos mais baratos antes que a fatura chegue.

Referência de ferramentas | Configuração | Contribuição | Solução de problemas

Principais recursos

Detalhamento de custo por ferramenta: Veja exatamente quais chamadas de ferramenta estão consumindo mais tokens e orçamento.
Alertas de orçamento: Defina um limite de gastos por sessão e receba avisos em 80% e 100% antes de excedê-lo.
Contagem de tokens offline: Usa js-tiktoken para contagens precisas — sem chamadas de API necessárias.
Sugestões de roteamento de modelos: Recomenda modelos mais baratos para o tipo de tarefa atual (consultivo, nunca aplicado sem aceitação explícita).
Preços multi-provedor: Rastreia custos entre modelos Claude, OpenAI e Gemini a partir de uma única tabela de preços configurável.
Histórico de gastos: Consulte totais diários, semanais e mensais por modelo ou ferramenta.
Alocação de custos por projeto: Marque sessões com nomes de projetos e gere relatórios de chargeback.
Relatórios de gastos em HTML: Exporte um relatório HTML autônomo de arquivo único com gráficos e status do orçamento.
Log de auditoria: Log somente de acréscimos de cada decisão de aplicação de orçamento.

Por que isto em vez de rastreadores de custo baseados em proxy?

A maioria das ferramentas de rastreamento de custos funciona roteando todo o tráfego de API pelo servidor delas e medindo tokens no lado do servidor. Isso significa que seus prompts e respostas passam por um serviço de terceiros, e você fica dependente da disponibilidade deles.

	mcp-cost-tracker-router	Rastreadores baseados em proxy (Helicone, LLMonitor, etc.)
Contagem de tokens	Offline via js-tiktoken — sem chamada de rede	Contada no lado do servidor após o tráfego ser roteado por proxy
Residência de dados	Somente SQLite local	Prompts + respostas passam por servidores de fornecedores
Roteamento de modelos	Ferramenta `suggest_model_routing` integrada	Raramente incluído; geralmente um nível pago separado
Multi-provedor	Claude, OpenAI, Gemini em uma tabela de preços	Frequentemente de um único provedor ou requer configuração separada
Dependência de disponibilidade	Nenhuma — totalmente offline	Quebra se o proxy estiver fora do ar

Se seus prompts contêm informações sensíveis ou você não pode rotear tráfego por um terceiro, esta é a ferramenta certa. Se você precisa de um painel gerenciado com compartilhamento em equipe, um serviço baseado em proxy pode ser mais adequado.

Avisos

mcp-cost-tracker-router armazena metadados de chamadas de ferramentas (contagens de tokens, nomes de modelos, carimbos de data/hora) localmente em SQLite. Não armazena conteúdo de prompts ou respostas. Os cálculos de custo são estimativas baseadas em uma tabela de preços local e podem não corresponder exatamente à fatura do seu provedor.

Requisitos

Node.js v20.19 ou mais recente.
npm.

Começando

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest"]
    }
  }
}

Para definir um alerta de orçamento de sessão:

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest", "--budget-alert=5.00"]
    }
  }
}

Configuração do cliente MCP

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

Seu primeiro prompt

Digite o seguinte no seu cliente MCP para verificar se tudo está funcionando:

How much has this session cost so far?

Seu cliente deve retornar um resumo de tokens e custo em USD para a sessão atual.

Ferramentas

Sessão (4 ferramentas)

get_session_cost — Retorna totais de tokens e estimativas de custo em USD para a sessão atual. Somente leitura.
get_tool_costs — Retorna o detalhamento de custo por ferramenta para a sessão, ordenado por custo decrescente. Somente leitura.
reset_session — Inicia uma nova sessão de rastreamento de custos. Os dados da sessão anterior são mantidos no histórico.
record_usage — Registra o uso de tokens para uma chamada de ferramenta. Recebe tool_name, model (opcional), input_tokens e output_tokens. Emite uma notificação de aviso de orçamento se 80% do limite for atingido.

Orçamentos e roteamento (3 ferramentas)

set_budget_alert — Define um limite de orçamento em USD (threshold_usd). Avisa em 80% e 100% do limite. Use com --enforce-budget para bloquear chamadas além do limite.
suggest_model_routing — Recomendação heurística de modelo por tipo de tarefa. Recebe task_description e constraints.max_cost_usd opcional. Retorna modelo recomendado com justificativa e custo estimado.
check_routing_policy — Verifica se um modelo é permitido para um determinado tipo de tarefa sob a política de roteamento. Recebe task_type e model.

Histórico e relatórios (4 ferramentas)

get_spend_history — Consulta gastos históricos agregados por period (day/week/month). Retorna detalhamento por modelo e ferramenta. Somente leitura.
estimate_workflow_cost — Estimativa de custo pré-execução para um fluxo de trabalho de múltiplas etapas. Recebe um array de steps com tool_name, estimated_input_tokens, estimated_output_tokens e model opcional. Somente leitura.
export_spend_report — Gera um relatório de gastos em HTML de arquivo único com detalhamento da sessão, gastos históricos, comparação de custos por modelo e status do orçamento. Somente leitura.
export_budget_audit — Exporta o log de auditoria das decisões de aplicação de orçamento. Aceita from_date, to_date e format opcionais (json/csv). Somente leitura.

Alocação de projetos (4 ferramentas)

set_project — Cria ou atualiza um projeto com um budget_usd opcional. Recebe project_name.
tag_session — Marca a sessão atual com um project_name para alocação de custos.
get_project_costs — Obtém o relatório de custos de um projeto. Recebe project_name e since opcional (data ISO). Somente leitura.
export_chargeback — Gera um relatório de chargeback para faturamento interno. Recebe from_date, to_date, group_by opcional (project/session) e format opcional (json/csv). Somente leitura.

Configuração

`--budget-alert`

Limite de gastos da sessão em USD. Um aviso é retornado quando os custos da sessão atingem 80% e novamente em 100% deste limite.

Tipo: number

`--db` / `--db-path`

Caminho para o arquivo de banco de dados SQLite usado para armazenar o histórico de custos.

Tipo: string Padrão: ~/.mcp/costs.db

`--pricing-table`

Caminho para um arquivo JSON contendo preços personalizados de modelos ($/1K tokens). Mesclado com a tabela integrada; modelos ausentes usam os padrões.

Tipo: string

`--default-model`

Nome do modelo para atribuir custos quando nenhum modelo pode ser inferido do contexto.

Tipo: string Padrão: claude-sonnet-4-6

`--enforce-budget`

Bloqueia chamadas de ferramentas que fariam a sessão exceder o limite de alerta de orçamento. Requer que --budget-alert esteja definido.

Tipo: boolean Padrão: false

`--http-port`

Inicia em modo HTTP usando transporte Streamable HTTP em vez de stdio. Útil para compartilhar uma única instância de rastreamento de custos entre uma equipe.

Tipo: number Padrão: desabilitado (usa stdio)

Passe flags via a propriedade args na sua configuração JSON:

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-cost-tracker-router@latest",
        "--budget-alert=2.00",
        "--enforce-budget"
      ]
    }
  }
}

Modelos suportados e preços

Tabela de preços integrada (USD por 1K tokens):

Modelo	Entrada	Saída
claude-opus-4-6	$0.0150	$0.0750
claude-sonnet-4-6	$0.0030	$0.0150
claude-haiku-4-5	$0.0008	$0.0040
gpt-4o	$0.0025	$0.0100
gpt-4o-mini	$0.000150	$0.000600
gemini-1.5-pro	$0.001250	$0.005000
gemini-1.5-flash	$0.000075	$0.000300
gemini-2.0-flash	$0.000100	$0.000400

Substitua preços de modelos individuais com --pricing-table. Todos os custos são estimativas.

Verificação

Antes de publicar uma nova versão, verifique o servidor com o MCP Inspector para confirmar que todas as ferramentas estão expostas corretamente e que o handshake do protocolo é bem-sucedido.

Interface interativa (abre o navegador):

npm run build && npm run inspect

Modo CLI (scriptado / amigável para CI):

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a read-only tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name get_session_cost

# Call record_usage with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name record_usage \
  --tool-arg tool_name=my_tool --tool-arg input_tokens=500 --tool-arg output_tokens=200

Execute antes de publicar para detectar regressões no registro de ferramentas e na inicialização do runtime.

Contribuição

Atualize src/pricing.ts quando novos modelos forem lançados. Todas as alterações no cálculo de custos devem incluir testes unitários com contagens de tokens conhecidas e valores USD esperados. As sugestões de roteamento ficam em src/tools/routing.ts.

npm install && npm test

Registro MCP e Marketplace

Este plugin está disponível em:

Pesquise por mcp-cost-tracker-router.