{
  "markdown": "# mcp-nfse-nacional\n\nMCP Server para consulta de Notas Fiscais de Serviço Eletrônicas (NFSe) no portal nacional ([nfse.gov.br](https://www.nfse.gov.br)). Permite que agentes de IA autentiquem-se com certificado digital e-CNPJ/e-CPF e consultem, detalhem e baixem PDFs de NFSe emitidas.\n\n## Ferramentas disponíveis\n\nO servidor expõe três ferramentas via protocolo MCP:\n\n| Ferramenta | Descrição | Parâmetros |\n|---|---|---|\n| `nfse_buscar` | Busca NFSe emitidas em um período. Retorna lista com data, destinatário, valor, status e chave de cada nota. | `data_inicio` (YYYY-MM-DD), `data_fim` (YYYY-MM-DD) |\n| `nfse_detalhes` | Obtém os detalhes completos de uma NFSe a partir da sua chave. Retorna cabeçalho, emitente, valores, DPS e salva o XML localmente. | `chave` (string) |\n| `nfse_pdf` | Baixa o PDF (DANFSe) de uma NFSe a partir da sua chave. Retorna o caminho do arquivo PDF salvo localmente. | `chave` (string) |\n\n> A autenticação é gerenciada automaticamente. O login é realizado na primeira chamada e, caso a sessão expire (erro de autenticação), uma nova tentativa de login é feita de forma transparente.\n\n## Variáveis de ambiente\n\n| Variável | Obrigatória | Padrão | Descrição |\n|---|---|---|---|\n| `CERT_FILE` | **Sim** | — | Caminho para o arquivo do certificado digital (`.pfx` / `.p12`), relativo ao diretório do projeto ou absoluto. |\n| `CERT_PASSWORD` | **Sim** | — | Senha do certificado digital. |\n| `MCP_TRANSPORT` | Não | `stdio` | Modo de transporte do servidor MCP. Valores aceitos: `stdio` ou `streamable-http`. |\n| `MCP_HOST` | Não | `127.0.0.1` | Endereço de bind do servidor HTTP (somente no modo `streamable-http`). |\n| `MCP_PORT` | Não | `3000` | Porta do servidor HTTP (somente no modo `streamable-http`). |\n| `STORAGE_PATH` | Não | `./storage` | Diretório onde os XMLs e PDFs baixados serão armazenados. |\n\nVocê pode definir as variáveis em um arquivo `.env` na raiz do projeto.\n\n## Executando via npx\n\n### Modo stdio (padrão)\n\nIdeal para integração direta com clientes MCP (Claude Desktop, VS Code, etc.):\n\n```bash\nCERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha npx -y mcp-nfse-nacional\n```\n\nExemplo de configuração em um cliente MCP (`mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"nfse-nacional\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-nfse-nacional\"],\n      \"env\": {\n        \"CERT_FILE\": \"/caminho/absoluto/para/certificado.pfx\",\n        \"CERT_PASSWORD\": \"sua_senha\"\n      }\n    }\n  }\n}\n```\n\n### Modo Streamable HTTP\n\nIdeal para ambientes onde o servidor precisa ficar escutando conexões HTTP:\n\n```bash\nCERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=3000 npx -y mcp-nfse-nacional\n```\n\nO endpoint MCP ficará disponível em `http://127.0.0.1:3000/mcp`.\n\nExemplo de configuração em um cliente MCP (`mcp.json`):\n\n```json\n{\n  \"servers\": {\n    \"nfse-nacional\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://127.0.0.1:3000/mcp\"\n    }\n  }\n}\n```\n\n## Executando via Docker (Streamable HTTP)\n\n### Build da imagem\n\n```bash\ndocker build -t mcp-nfse-nacional .\n```\n\n### Execução\n\n```bash\ndocker run -d \\\n  --name mcp-nfse-nacional \\\n  -p 3000:3000 \\\n  -v /caminho/para/certificado.pfx:/app/certificado.pfx:ro \\\n  -v /caminho/para/storage:/app/storage \\\n  -e CERT_FILE=certificado.pfx \\\n  -e CERT_PASSWORD=sua_senha \\\n  mcp-nfse-nacional\n```\n\nO endpoint MCP ficará disponível em `http://localhost:3000/mcp`.\n\n> O Dockerfile já define `MCP_TRANSPORT=streamable-http`, `MCP_HOST=0.0.0.0` e `MCP_PORT=3000` por padrão.\n\n## Segurança\n\n> ⚠️ **O certificado digital é um ativo crítico.** Ele possui validade jurídica e representa a identidade da sua empresa ou pessoa física perante a Receita Federal e demais órgãos. Trate-o com o mesmo cuidado que trataria uma senha-mestre.\n\n### Orientações essenciais\n\n- **Nunca versione o certificado (`.pfx` / `.p12`) ou sua senha em repositórios Git.** Adicione `*.pfx`, `*.p12` e `.env` ao seu `.gitignore`.\n- **Não exponha o servidor HTTP publicamente.** No modo `streamable-http`, o servidor não possui autenticação própria. Mantenha-o acessível apenas em `127.0.0.1` ou proteja-o com um reverse proxy autenticado (com mTLS, API key, etc.).\n- **Use variáveis de ambiente ou secrets managers** para fornecer a senha do certificado. Evite passá-la como argumento de linha de comando, pois ela pode ficar visível no histórico do shell e na listagem de processos (`ps`).\n- **Monte o certificado como somente leitura** no Docker (flag `:ro`), minimizando riscos de alteração acidental.\n- **Restrinja permissões do arquivo do certificado** no sistema de arquivos (`chmod 400 certificado.pfx`).\n- **Monitore a expiração do certificado.** Certificados digitais possuem validade (geralmente 1 a 3 anos). Tenha um processo para renovação.\n- **Armazenamento local de XMLs e PDFs:** os arquivos baixados são salvos no diretório `storage/`. Garanta que esse diretório tenha permissões adequadas e que os dados fiscais sejam tratados conforme as políticas de privacidade da sua organização.\n",
  "bytes": 5044,
  "sha": "1c3459f715cdb8dda9b4ea5289b300d82f7761f7ed057ba05a95a13b3b4eaa8b",
  "repo_slug": "samuelmoraesf/mcp-nfse-nacional",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_samuelmoraesf_mcp_nfse_naciona_3ba02c42/readme"
}