brasilnfe-mcp

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./assets/logo-brasilnfe-branca.png">
  <img src="./assets/logo-brasilnfe.png" alt="Brasil NFe" width="320">
</picture>

# Brasil NFe MCP

**Servidor MCP fiscal brasileiro - sua IA emite NF-e, NFC-e, NFS-e, CT-e, MDF-e e DC-e.**

[Site](https://www.brasilnfe.com.br) - [Documentação MCP](https://www.brasilnfe.com.br/mcp) - [Demo ao vivo](https://www.brasilnfe.com.br/ai/) - [Painel](https://api.brasilnfe.com.br)

[English](README.en.md) - Português

</div>

---

## O que é

O **Brasil NFe MCP** é o primeiro servidor MCP (Model Context Protocol) que expõe a infraestrutura fiscal brasileira inteira como ferramentas, recursos e prompts pra qualquer cliente compatível com MCP - Claude Desktop, Cursor, Windsurf, VS Code Copilot, Zed, Continue.dev, JetBrains, ou sua própria aplicação.

Plugue o servidor no seu cliente MCP e o agente de IA passa a **emitir nota fiscal por linguagem natural** direto na conversa - "emite uma NFC-e de R$ 89,90 pro CPF tal" - e o documento vai pra SEFAZ. A IA descobre as tools sozinha, monta o payload pelo schema e traduz erros da SEFAZ pra linguagem clara.

## REST API ou MCP?

Os dois são produtos de primeira linha da Brasil NFe e expõem a **mesma** infraestrutura fiscal - mesmo backend SEFAZ, mesmo SLA, mesmo suporte humano. A escolha é pelo tipo de integração, não pela qualidade:

| Use a **[API REST](https://www.brasilnfe.com.br/docs)** quando | Use o **MCP** quando |
|---|---|
| Você tem ERP, sistema de gestão ou app próprio com fluxo de emissão já definido | Quer um assistente IA, copilot ou agente decidindo quando e como emitir |
| O processamento é em lote, agendado ou movido por evento de fila/webhook | O fluxo é conversacional - usuário (ou agente) no loop dirigindo cada passo |
| A integração é determinística e você tem controle pixel-perfect da UI/UX | O cliente quer plugar Claude / Cursor / Copilot do contador direto na operação |
| Volume alto, paralelismo otimizado, contratos de payload estáveis | Sessão interativa, exploratória, ad-hoc por linguagem natural |

> Os dois conversam com o mesmo backend - **dá pra ter o ERP integrado via REST e ao mesmo tempo plugar a IA do contador no MCP**. Quando uma rota nova entra na API REST, ela já vira tool MCP automaticamente. Roadmap fiscal unificado, dois canais de consumo.

## Endpoint público

```
https://api.brasilnfe.com.br/services/Mcp
```

| Recurso | Método | Caminho |
|---|---|---|
| JSON-RPC | `POST` | `/services/Mcp` |
| SSE stream | `GET` | `/services/Mcp` |
| Encerrar sessão | `DELETE` | `/services/Mcp` |
| Discovery | `GET` | `/.well-known/mcp` |
| Health | `GET` | `/services/Mcp/info` |

- **Transport:** Streamable HTTP
- **Spec:** MCP `2025-06-18`
- **Auth:** Bearer token (`Authorization: Bearer <TOKEN>`)
- **Rate-limit:** 60 requisições/minuto por token (default)

## O que está exposto

### 30+ tools em 8 categorias

| Categoria | Tools | O que faz |
|---|---|---|
| **NF-e / NFC-e** | `nfe_emitir`, `nfe_emitir_complementar`, `nfe_previsualizar` | Emite produto B2B (modelo 55) ou cupom de varejo (modelo 65), gera DANFE prévio |
| **NFS-e** | `nfse_emitir`, `nfse_consultar` | Emite e consulta nota de serviço (5.500+ regras municipais embutidas) |
| **CT-e** | `cte_emitir`, `cte_desacordo` | Emite conhecimento de transporte, registra desacordo do tomador |
| **MDF-e** | `mdfe_emitir`, `mdfe_encerrar` | Emite manifesto de carga, encerra ao fim do transporte |
| **DC-e** | `dce_emitir` | Emite declaração de conteúdo (PF/MEI) |
| **NF-EnerCom** | `nfenercom_gerar_arquivo`, `nfenercom_emitir` | Emite NF de energia comercializada |
| **Eventos fiscais** | `evento_cancelar`, `evento_carta_correcao`, `evento_manifestar`, `evento_inutilizar` | Cancela, corrige (CC-e), manifesta destinatário, inutiliza numeração |
| **Consultas SEFAZ** | `sefaz_status`, `cadastro_consultar`, `nota_listar`, `imposto_calcular` | Status do serviço, IE, listagem de notas, simulador de impostos |
| **Cadastros** | `cliente_consultar/criar/editar`, `produto_consultar/criar/editar`, `tributacao_consultar/criar/editar` | CRUD completo de clientes, produtos e regras tributárias (com fallback Receita Federal) |
| **Arquivos** | `arquivo_baixar`, `arquivo_baixar_evento`, `arquivo_baixar_periodo` | Baixa XML/PDF individual ou ZIP do período |
| **Auxiliares** | `fci_gerar`, `health` | Gera FCI (conteúdo importado), health-check |

### 5 resources (URI scheme `brasilnfe://`)

- `brasilnfe://empresa/atual` - snapshot da empresa logada
- `brasilnfe://nfe/{chave}/xml` - XML autorizado
- `brasilnfe://nfe/{chave}/danfe` - DANFE em PDF
- `brasilnfe://evento/{chave}/{seq}` - evento por sequencial
- `brasilnfe://recebidas/{periodo}` - notas recebidas no período

### 5 prompts prontos

- `emitir_nfe_simples` - fluxo guiado de emissão NF-e
- `cancelar_nota` - cancelamento com validação de prazo
- `diagnostico_emissao` - checagem completa antes de emitir
- `relatorio_periodo` - relatório fiscal do período
- `carta_correcao` - fluxo de CC-e com validação de campos permitidos

## Quick start

### 1. Pegue seu token

Crie uma conta gratuita em [brasilnfe.com.br](https://www.brasilnfe.com.br) e copie o token no [painel](https://api.brasilnfe.com.br). Modo homologação é grátis - você emite documentos de teste à vontade sem nada ir pra SEFAZ de produção.

### 2. Configure seu cliente MCP

Pega o arquivo correto em [`examples/`](examples/) e cola na config do seu cliente:

- [Claude Desktop](examples/claude-desktop.json)
- [Cursor](examples/cursor.json)
- [Windsurf](examples/windsurf.json)
- [VS Code Copilot](examples/vscode-copilot.json)
- [Zed](examples/zed.json)
- [cURL puro (JSON-RPC)](examples/curl.md)

Substitua `SEU_TOKEN_AQUI` pelo token real e reinicie o cliente.

### 3. Fala com a IA

```
"Liste o status da SEFAZ pra SP."
"Consulte o CNPJ 39.658.743/0001-99."
"Emite uma NFC-e de R$ 89,90 pro consumidor com CPF 123.456.789-00."
"Cancela a chave 35..., justificativa: erro de digitação no valor."
```

Pronto. A IA descobre as tools sozinha, pede o que falta, valida, monta o payload, envia pra SEFAZ, e te entrega chave + protocolo + XML + PDF.

## Demo sem cadastro

Abra **[brasilnfe.com.br/ai](https://www.brasilnfe.com.br/ai/)** e converse com o assistente fiscal direto no navegador. Não envia pra SEFAZ de produção, mas mostra o fluxo completo com DANFE renderizado em tempo real ao lado do chat.

## Boas práticas

- **Sempre rode em homologação (`tipoAmbiente: 2`) antes de produção.** Documento de teste tem CNPJ permitido e numeração separada - zero risco fiscal.
- **Consulte cliente/produto/tributação antes de criar.** As tools `*_consultar` evitam duplicatas e dão à IA o contexto pra reusar cadastros existentes.
- **Confirme operações destrutivas.** Cancelamento e inutilização são irreversíveis - a IA já é instruída a confirmar, mas verifique no seu fluxo.
- **Feche sessões idle.** `DELETE /services/Mcp` libera quota mais cedo.
- **Auditoria sai automática.** Todas as chamadas MCP ficam logadas no painel da sua empresa por 5 anos (LGPD-compliant).

## Suporte

- **Documentação:** [brasilnfe.com.br/mcp](https://www.brasilnfe.com.br/mcp)
- **Demo ao vivo:** [brasilnfe.com.br/ai](https://www.brasilnfe.com.br/ai/)
- **WhatsApp:** [+55 (31) 9 7168-5947](https://wa.me/5531971685947) (horário comercial)
- **E-mail:** contato@brasilnfe.com.br (24/7)
- **LGPD/DPO:** dpo@brasilnfe.com.br

## Sobre

Mantido pela **[Brasil NFe LTDA](https://www.brasilnfe.com.br)** (CNPJ 39.658.743/0001-99), fundada em 2019 em Ipatinga/MG por Maxsuel Lima. Especialista em automação fiscal brasileira: 6 documentos fiscais cobertos, 5.500+ regras municipais NFS-e, 543 códigos SEFAZ embutidos, PCI DSS, e suporte humano 24/7.

## Licença

[MIT](LICENSE) - você pode usar, modificar e distribuir livremente este repositório (configs, exemplos e docs). O servidor MCP em si é serviço operado pela Brasil NFe LTDA - veja [Termos de Uso](https://www.brasilnfe.com.br/termos) e [Política de Privacidade](https://www.brasilnfe.com.br/privacidade).