# NFe.io MCP > NFe.io MCP Server manages Brazilian fiscal documents. Your AI agent uses this server to issue, cancel, and retrieve service and merchandise invoices (NFS-e/NF-e). It also validates municipal codes (IBGE) and maintains corporate tax metadata directly from your workflow. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** nfeio, fiscal-automation, nfs-e, brazilian-taxes, invoice-api, ibge-codes ## Description Listen up. If you're dealing with Brazilian fiscal documents—the whole shebang of invoices and corporate tax stuff—you need **NFe.io**. This isn't some flimsy API wrapper; it's a full-stack MCP that manages the entire lifecycle of your financial records, from setting up a new entity to canceling an invoice years later. Your AI agent connects here to handle all the complex state changes in Brazilian tax law for you. ### Managing Your Corporate Identity You gotta know who you are before you can bill anybody. You tell your agent to use `create_company` and it registers a brand new corporate entity, giving you the necessary ID to start issuing documents through NFe.io. If you've got multiple business fronts running, `list_companies` spits out every company registered under your account so you can pick the right one. Need the deep details on one specific issuer? Run `get_company_details`. It pulls all the granular fiscal and tax metadata for that corporate ID—everything you need to know about their compliance status. ### Issuing Invoices: Goods or Services When it's time to bill, this server handles both types of transactions. You can generate a new physical goods invoice (the NF-e) by calling `issue_merchandise_invoice`. This tool makes sure the resulting document is compliant with all Brazilian tax rules for merchandise sales. If you're billing for services rendered—like consulting hours or setup fees—you use `issue_service_invoice` to generate the required service invoice (NFS-e). Both functions create and issue the documents, making them instantly usable. ### Retrieving and Correcting Invoices Life happens, right? Sometimes an invoice needs correcting, or you just need a copy of what was issued. To pull up all the details for any existing physical goods invoice (NF-e), your agent uses `get_merchandise_invoice` with the unique ID. It doesn't just give you basic info; it pulls the full status and every detail about that specific merchandise document, including links to download both the PDF and XML files. Same deal for services: `get_service_invoice` retrieves all the details for an existing service invoice (NFS-e). If an invoice needs reversing—whether it's goods or services—you use dedicated tools. To reverse a physical goods transaction, call `cancel_merchandise_invoice`. For services, you run `cancel_service_invoice`. These functions ensure the reversal is processed correctly through the system. ### Advanced Operations and Webhooks Beyond just invoices, this server handles backend setup too. If your business process requires external notifications—say, when an invoice changes status—you can use `list_webhooks` to see every single one of those configured endpoints. You also manage the credentials for your agent; if you ever need a list of all companies registered, running `list_companies` is your go-to move. ## Tools ### cancel_service_invoice Reverses an already issued service invoice (NFS-e). ### create_company Registers a new company entity, allowing it to issue invoices through NFe.io. ### get_company_details Pulls detailed fiscal and tax information for a specific company issuer ID. ### get_merchandise_invoice Retrieves all details about an existing physical goods invoice (NF-e). ### get_service_invoice Retrieves all details about an existing service invoice (NFS-e). ### issue_merchandise_invoice Creates and issues a new physical goods invoice (NF-e) compliant with Brazilian tax rules. ### issue_service_invoice Generates and issues a new service invoice (NFS-e) for billing services rendered. ### list_companies Provides a list of every company entity currently registered under your NFe.io account. ### list_webhooks Lists all the external webhooks you have configured for notifications from NFe.io. ### cancel_merchandise_invoice Reverses an already issued physical goods invoice (NF-e). ## Prompt Examples **Prompt:** ``` List all active companies in my NFe.io account. ``` **Response:** ``` I've retrieved your company list. You have 2 active entities: 1. Tech Services Ltda (ID: comp_1), 2. Consulting Group (ID: comp_2). Which one would you like to use for invoice issuance? ``` **Prompt:** ``` Check the status of service invoice ID 'inv_nfe_999888'. ``` **Response:** ``` Connecting to NFe.io gateway... Invoice 'inv_nfe_999888' is currently 'Issued' (Autorizada). I've found the official download links: [Download PDF](...) and [Download XML](...). Would you like me to send these to you? ``` **Prompt:** ``` Find the IBGE code for the city of 'São Paulo'. ``` **Response:** ``` Searching municipal codes... I found the IBGE code for São Paulo (SP): `3550308`. This code is active and compatible with the NFe.io service invoice engine. ``` ## Capabilities ### Issue Invoice Create and issue both Service Invoices (NFS-e) and Merchandise Invoices (NF-e). ### Cancel Invoice Reverse issued invoices using dedicated tools for service or merchandise types. ### Retrieve Details Get the full status and details of any existing invoice by its unique ID, including download links for PDF/XML. ### Manage Company Records List all registered companies or pull detailed tax metadata for a specific corporate issuer. ### Validate Tax Codes Check municipal compatibility and validate IBGE codes necessary for compliant invoicing. ## Use Cases ### Client Onboarding and Billing A new client signs up (Problem). The agent first runs `get_company_details` using the provided CNPJ to check their tax status. If good, it then uses `issue_service_invoice`, generating the required NFS-e document automatically for billing. ### Post-Sale Adjustment A client reports an error on a recent invoice (Problem). The agent first runs `get_service_invoice` to pull the original ID and status. Once verified, it uses `cancel_service_invoice` before issuing a corrected replacement. ### Bulk Reconciliation The accounting team needs monthly records (Problem). The agent executes `list_companies`, gets a list of all entities, and then iterates through them using `get_merchandise_invoice` to pull all necessary XML data for reconciliation. ### System Health Check You need to know if your webhook setup is accurate (Problem). The agent runs `list_webhooks` first, and then uses the resulting list to confirm that every required billing event has a configured notification endpoint. ## Benefits - **Automated Billing:** Instead of writing complex integration code for every tax rule, use `issue_service_invoice` to generate compliant NFS-e documents in one call. Your agent handles the state changes; you just provide the payload. - **Instant Status Checks:** Need to know if an invoice cleared? Use `get_merchandise_invoice` or `get_service_invoice`. You get immediate status updates and download links for both PDF and XML, eliminating manual portal checks. - **Compliance Guardrails:** Before billing, validate the location. The server lets you check municipal compatibility using IBGE codes, stopping failed invoices before they even start. This prevents costly failures down the line. - **Company Setup Made Simple:** Don't manually set up every client. Use `create_company` to register a new issuer and then use `get_company_details` to pull their tax metadata for immediate billing readiness. - **Audit Trail Management:** When an invoice needs adjustment, don't guess the process. Explicitly run `cancel_service_invoice` to ensure proper reversal records are created, keeping your books clean. ## How It Works The bottom line is: You hand off the complex compliance logic to the server; your AI client just needs to know which action to trigger. 1. First, you subscribe to the NFe.io MCP Server and log into your dashboard. 2. Next, you pull the API Key and Company ID credentials required for issuing transactions. 3. Finally, you instruct your agent (e.g., 'Issue an NFS-e for this client') and it runs the appropriate tool against the live Brazilian fiscal system. ## Frequently Asked Questions **How do I cancel a service invoice using the `cancel_service_invoice` tool?** You pass the specific Service Invoice ID to the tool. The server handles the reversal process and ensures all necessary accounting adjustments are recorded automatically. **Which tool should I use to list all my registered companies? Use `list_companies`.** `list_companies` pulls a complete roster of every company entity associated with your account. This is the first step if you need to know which entities are available for billing. **I need to get the XML and PDF links for an invoice. Which tool should I use? Use `get_service_invoice` or `get_merchandise_invoice`.** Both retrieval tools (`get_service_invoice`/`get_merchandise_invoice`) return a detailed payload that includes direct download links for both the PDF and XML versions, making them perfect for automated reporting. **What is the best way to start a new invoicing workflow? Use `create_company` first.** `create_company` registers a new issuer entity in NFe.io. This must happen before you can successfully issue any invoices for that specific legal entity. **Before I run `get_company_details`, what credentials do I need for authentication?** You must use an API Key and your Company ID. The server requires these two parameters to authenticate the request. Always grab your keys from the NFe.io Dashboard settings before calling any company-specific tool. **If I use `issue_service_invoice` with incorrect fiscal data, how do I know what went wrong?** The tool returns a structured error code and message. It doesn't just fail; it tells you exactly which field—like the IBGE code or tax ID—is incompatible with Brazilian standards. Check the response payload for specific validation errors. **How can I monitor real-time updates using `list_webhooks`?** You don't use `list_webhooks` to receive data; you use it to see what webhooks are configured. To actually monitor changes, you must set up a webhook endpoint in the NFe.io Dashboard that points back to your system. **When I run `get_merchandise_invoice`, does it provide all related tax metadata?** Yes, it provides a detailed payload containing not only the invoice status but also the associated fiscal records and tax coefficients. This means your AI agent gets enough data to process compliance reports without needing extra calls. **Can my AI automatically issue an NFS-e for a specific customer?** Yes! Use the `issue_service_invoice` tool with the Company ID and a JSON payload containing the customer data and service values. Your agent will trigger the issuance process with the relevant municipality. **How do I find the correct IBGE code for a Brazilian city?** You can use the `list_cities` tool to search for municipalities by name or state. The agent will return the official IBGE codes required for fiscal document validation. **Can I retrieve the download link for an invoice PDF?** Yes! Use the `get_service_invoice` tool with the unique Invoice ID. Your agent will return the metadata, including official links to download the PDF and XML versions of the document.