Skip to main content
Glama

SEFAZ Monitor MCP & REST API

Netlify Status License: MIT MCP Protocol Node.js

Servidor open-source que implementa o Model Context Protocol (MCP) e uma API REST de alta performance para monitorar em tempo real a disponibilidade de todos os servidores da Secretaria da Fazenda (SEFAZ) nos 27 estados do Brasil.

Desenvolvido para conectar agentes autônomos de IA (Claude, ChatGPT, Cursor, Dify, LibreChat, OpenWebUI) e sistemas ERP diretamente ao status operacional dos autorizadores fiscais.


Acesso Rápido


Related MCP server: HiveCloud CT-e / MDF-e

Principais Funcionalidades

  • Protocolo MCP (versão 2024-11-05): Suporta transporte moderno Streamable HTTP (requisições JSON-RPC 2.0 via POST) e Server-Sent Events (SSE).

  • Roteamento Inteligente de Autorizadores: Resolve automaticamente se um estado usa Autorizador Próprio (ex: SEFAZ Bahia para NF-e, SEFAZ São Paulo) ou Autorizador Virtual (SVRS ou SVAN).

    • Exemplo: Na Bahia (BA), a NF-e roda no autorizador próprio da Bahia, enquanto a NFC-e roda na SVRS (Sefaz Virtual do RS). O servidor identifica e reporta essa diferença com exatidão.

  • Cobertura Completa de Documentos Fiscais: NF-e (modelo 55), NFC-e (modelo 65), CT-e (modelo 57) e MDF-e (modelo 58).

  • Deploy Serverless Contínuo: Configurado no Netlify (netlify.toml + netlify/functions/mcp.js), com deploy automático a cada commit na branch main.

  • Cache Inteligente: Cache em memória com TTL de 60 segundos para evitar sobrecarga nas fontes e garantir respostas sub-segundo.

  • Formatação para Agentes: As ferramentas retornam resumos em texto objetivo com esferas de status (🟢 Operacional, 🟡 Instável, 🔴 Fora do Ar) acompanhados do payload JSON estruturado.


Catálogo de Ferramentas MCP (Tools)

Ferramenta

Descrição

Parâmetros

consultar_status_geral_sefaz

Panorama geral da SEFAZ no país (status consolidado, total de incidentes ativos e manutenções).

(Nenhum)

consultar_status_uf

Consulta o status de uma UF específica e tipo de documento. Resolve o autorizador próprio ou virtual.

uf (obrigatório, ex: "BA", "SP")tipo_documento (opcional: "TODOS", "NFE", "NFCE", "CTE", "MDFE")

consultar_incidentes_sefaz

Lista incidentes em andamento, alertas de lentidão e manutenções programadas.

apenas_ativos (opcional, booleano, padrão: true)

listar_todos_estados_sefaz

Tabela consolidada dos 27 estados para auditoria ou montagem de painéis.

tipo_documento (opcional, padrão: "NFE")apenas_com_problemas (opcional, padrão: false)


Como Conectar ao seu Cliente MCP

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sefaz-monitor": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://monitorsefazmcp.netlify.app/mcp"]
    }
  }
}

Para Claude Code, adicione via terminal:

claude mcp add --transport http sefaz-monitor https://monitorsefazmcp.netlify.app/mcp

2. Cursor IDE (.cursor/mcp.json)

Adicione em Settings > Features > MCP ou no arquivo .cursor/mcp.json:

{
  "mcpServers": {
    "sefaz-monitor": {
      "url": "https://monitorsefazmcp.netlify.app/mcp"
    }
  }
}

3. Plataformas Web de Agentes (Dify, LibreChat, Chatwoot, Copilot)

  • Tipo de Transporte: Streamable HTTP (ou Server-Sent Events / SSE)

  • URL do Servidor: https://monitorsefazmcp.netlify.app/mcp

  • Método HTTP: POST

  • Cabeçalhos: Deixe vazio (ou envie Authorization: Bearer <SEU_TOKEN> caso a variável AUTH_TOKEN tenha sido configurada).


Instruções para o System Prompt do Agente

Cole o texto abaixo nas instruções de sistema do seu agente para orientá-lo na resolução de falhas:

Quando o usuário relatar falha, lentidão, rejeição de autorizador indisponível ou perguntar se a SEFAZ está operando, invoque a ferramenta consultar_status_uf informando a UF da empresa e o modelo do documento.
- Se a SEFAZ estiver com instabilidade ou queda: explique que a falha é no datacenter do Fisco (ou autorizador virtual SVRS/SVAN) e não no software de gestão. Oriente a emissão em Contingência Offline para NFC-e (com transmissão posterior) ou SVC para NF-e.
- Se a SEFAZ estiver 100% operacional: oriente a checagem de certificado digital A1/A3, liberação de firewall na porta 443, relógio do sistema e código numérico de rejeição da nota.

Como Rodar Localmente

# 1. Clonar o repositório
git clone https://github.com/PauloVictor1803/sefaz-monitor-mcp.git
cd sefaz-monitor-mcp

# 2. Instalar dependências
npm install

# 3. Iniciar o servidor de desenvolvimento
npm start
# ou com live reload:
npm run dev

# 4. Executar os testes automatizados
npm test

O servidor local ficará disponível em http://localhost:3000:

  • Painel: http://localhost:3000/

  • Endpoint MCP: http://localhost:3000/mcp

  • API REST Status Geral: http://localhost:3000/api/status

  • API REST Status UF: http://localhost:3000/api/uf?uf=BA


Integração Contínua e Deploy Automático (CI/CD)

Este repositório está configurado para Deploy Contínuo no Netlify:

  1. Todo commit ou pull request aprovado na branch main dispara automaticamente o Webhook de build do Netlify.

  2. O Netlify empacota as funções serverless e publica a versão mais recente em segundos.


Licença

Distribuído sob a licença MIT. Consulte o arquivo LICENSE para obter mais informações.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants and automation tools to query and analyze Brazilian fiscal data, including CNPJ, Simples Nacional, NF-e, NFS-e, SPED, eSocial, tax regime comparison, and supplier risk assessment without requiring API keys.
      44
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and business systems to query and validate Brazilian fiscal data and documents, including CNPJ/CPF, Simples Nacional/MEI, NF-e/NFS-e, SPED, eSocial, and supplier compliance, without mandatory API keys. It also supports offline reference tables, tax-regime comparison, due-diligence scoring, and 2026 IBS/CBS reform analysis through composable tools.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query Brazilian state tax registration (Inscrição Estadual) across all 27 states, CNPJ company records, and negative/debt clearance certificates (CND estadual, CNDT, CND federal, CRF/FGTS), and to download a read-only copy of an NF-e XML by its access key. Paid lookups draw on a FiscalAPI account balance and require an explicit cost confirmation, with two validation/coverage tools available free of charge.
      MIT