Ir para o conteúdo
OpenNota

MCP do OpenNota: nota fiscal no seu assistente de IA#

Conecte o Claude Code, o Cursor, o VS Code ou outro cliente MCP ao OpenNota e deixe o assistente ler a documentação, gerar o cliente da API e testar pedidos de NFCom, NFS-e e NF-e enquanto você programa.

O servidor MCP fica em https://api.opennota.com.br/v1/mcp. A documentação funciona sem credencial; validar, emitir e consultar usam a sua credencial de sandbox. O manual completo da API está em developer.opennota.com.br.

O que é#

O MCP (Model Context Protocol) é o padrão aberto que os assistentes de código usam para chamar ferramentas externas. Com o MCP do OpenNota, o assistente não precisa adivinhar o formato do pedido nem copiar exemplos desatualizados: ele consulta o manual oficial e testa o pedido na API de verdade, no ambiente de testes.

O que o assistente consegue fazer#

Pedido ao assistente Ferramenta usada Precisa de credencial
"Como assino as requisições do OpenNota?" opennota_buscar_documentacao, opennota_ler_documentacao não
"Escreva o cliente do OpenNota em PHP" opennota_gerar_cliente (node, python, php ou curl) não
"Monte um pedido de NFCom para este cliente" opennota_exemplo_pedido não
"O que significa IDEMPOTENCY_CONFLICT?" opennota_explicar_erro não
"Qual CFOP uso na remessa em comodato?" opennota_guia_fiscal não
"Minha credencial está funcionando?" opennota_ping sim
"Valide estes 50 cadastros antes do faturamento" opennota_validar, opennota_validar_lote sim
"Emita a nota de teste e me mostre o XML" opennota_emitir, opennota_consultar, opennota_xml sim
"Cancele a nota de teste" opennota_cancelar sim

A função de assinatura gerada para cada linguagem é testada contra o vetor de prova do manual a cada versão.

Segurança#

Como configurar#

Claude Code#

claude mcp add --transport http opennota https://api.opennota.com.br/v1/mcp \
  --header "X-OpenNota-Key: $OPENNOTA_KEY_ID" \
  --header "Authorization: Bearer $OPENNOTA_SECRET"

Para o time inteiro, no .mcp.json do projeto (as variáveis vêm do ambiente de cada pessoa):

{
  "mcpServers": {
    "opennota": {
      "type": "http",
      "url": "https://api.opennota.com.br/v1/mcp",
      "headers": {
        "X-OpenNota-Key": "${OPENNOTA_KEY_ID}",
        "Authorization": "Bearer ${OPENNOTA_SECRET}"
      }
    }
  }
}

VS Code#

Em .vscode/mcp.json. O VS Code pede o segredo na primeira vez e guarda fora do projeto:

{
  "inputs": [
    { "type": "promptString", "id": "opennota-secret", "description": "Segredo OpenNota (sandbox)", "password": true }
  ],
  "servers": {
    "opennota": {
      "type": "http",
      "url": "https://api.opennota.com.br/v1/mcp",
      "headers": {
        "X-OpenNota-Key": "<key_id de sandbox>",
        "Authorization": "Bearer ${input:opennota-secret}"
      }
    }
  }
}

Cursor e outros clientes#

Em ~/.cursor/mcp.json ou no arquivo de servidores MCP do seu cliente:

{
  "mcpServers": {
    "opennota": {
      "url": "https://api.opennota.com.br/v1/mcp",
      "headers": {
        "X-OpenNota-Key": "<key_id de sandbox>",
        "Authorization": "Bearer <segredo de sandbox>"
      }
    }
  }
}

Só para consultar a documentação, configure a URL sem headers.

Primeiros passos#

  1. Configure o servidor no seu cliente com a credencial de sandbox.
  2. Peça ao assistente: "teste a minha credencial do OpenNota". Ele usa opennota_ping e mostra o ambiente e as empresas liberadas.
  3. Peça: "gere o cliente do OpenNota na linguagem deste projeto e valide um pedido de exemplo".
  4. Quando o pedido validar sem erros, troque os dados de exemplo pelos do seu sistema.

Ainda não tem credencial? Solicite acesso.

Detalhes técnicos#