MCP Nfse Nacional

🚀 mcp-nfse-nacional

MCP Server for querying Electronic Service Invoices (NFSe) on the national portal (nfse.gov.br). It allows AI agents to authenticate with digital certificates (e-CNPJ/e-CPF) and query, view details, and download PDFs of issued NFSe.

🚀 Quick Start

The MCP server provides seamless access to query, detail, and download Electronic Service Invoices (NFSe) on the national portal. It supports authentication with digital certificates and offers multiple running modes.

✨ Features

The server exposes three tools via the MCP protocol:

Authentication is managed automatically. Login is performed on the first call, and if the session expires (authentication error), a new login attempt is made transparently.

📦 Installation

Environment Variables

You can define the variables in a .env file at the root of the project.

Running via npx

stdio Mode (Default)

Ideal for direct integration with MCP clients (Claude Desktop, VS Code, etc.):

CERT_FILE=./certificado.pfx CERT_PASSWORD=sua_senha npx -y mcp-nfse-nacional

Example configuration in an MCP client (mcp.json):

{
  "servers": {
    "nfse-nacional": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-nfse-nacional"],
      "env": {
        "CERT_FILE": "/caminho/absoluto/para/certificado.pfx",
        "CERT_PASSWORD": "sua_senha"
      }
    }
  }
}

Streamable HTTP Mode

Ideal for environments where the server needs to listen for HTTP connections:

CERT_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

The MCP endpoint will be available at http://127.0.0.1:3000/mcp.

Example configuration in an MCP client (mcp.json):

{
  "servers": {
    "nfse-nacional": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Running via Docker (Streamable HTTP)

Build the Image

docker build -t mcp-nfse-nacional .

Run the Container

docker run -d \
  --name mcp-nfse-nacional \
  -p 3000:3000 \
  -v /caminho/para/certificado.pfx:/app/certificado.pfx:ro \
  -v /caminho/para/storage:/app/storage \
  -e CERT_FILE=certificado.pfx \
  -e CERT_PASSWORD=sua_senha \
  mcp-nfse-nacional

The MCP endpoint will be available at http://localhost:3000/mcp.

The Dockerfile already sets MCP_TRANSPORT=streamable-http, MCP_HOST=0.0.0.0, and MCP_PORT=3000 by default.

📚 Documentation

Security

⚠️ Important Note

The digital certificate is a critical asset. It has legal validity and represents the identity of your company or individual before the Federal Revenue and other agencies. Treat it with the same care as you would a master password.

Essential Guidelines

• Never version the certificate (.pfx / .p12) or its password in Git repositories. Add *.pfx, *.p12, and .env to your .gitignore.
• Do not expose the HTTP server publicly. In streamable-http mode, the server has no built-in authentication. Keep it accessible only at 127.0.0.1 or protect it with an authenticated reverse proxy (using mTLS, API key, etc.).
• Use environment variables or secret managers to provide the certificate password. Avoid passing it as a command-line argument, as it may be visible in the shell history and process list (ps).
• Mount the certificate as read-only in Docker (using the :ro flag) to minimize the risk of accidental modification.
• Restrict file permissions for the certificate in the file system (chmod 400 certificado.pfx).
• Monitor the certificate expiration date. Digital certificates have an expiration date (usually 1 to 3 years). Have a process in place for renewal.
• Local storage of XMLs and PDFs: Downloaded files are saved in the storage/ directory. Ensure that this directory has appropriate permissions and that fiscal data is handled in accordance with your organization's privacy policies.