# ICMS Calculator MCP > ICMS Calculator provides specialized tools to calculate complex Brazilian ICMS taxes. It handles Tax Substitution (ST), tax differentials (DIFAL) for B2C sales, and determines grossed-up product bases using the 'inside' calculation method. Use it to retrieve correct interstate rates based on origin and destination regions for flawless financial reporting. ## Overview - **Category:** finance - **Price:** Free - **Tags:** icms, brazil, tax-calculator, st-calculation, difal, mva ## Description Calculating Brazilian ICMS taxes is a massive headache because the rules change constantly, depending entirely on where the goods start and where they end up. This MCP handles that complexity. You feed in your transaction details, and it figures out exactly what's owed—whether you need to calculate Tax Substitution (ST), figure out the tax differential for interstate B2C sales, or determine the correct grossed-up product value. It also looks up applicable rates between regions. When you use this MCP through Vinkius, your agent gets a single source of truth for compliance calculations, eliminating guesswork from cross-state commerce. ## Tools ### calculate_tax_differential Figures out the DIFAL amount needed specifically for B2C interstate transactions. ### calculate_icms_substitution Calculates the amount of ICMS-ST (Tax Substitution) that must be collected on a product. ### calculate_tax_base Computes the grossed-up product value using the 'inside' calculation method for tax bases. ### get_interstate_rate Retrieves the current, applicable tax rate between any specified Brazilian origin and destination regions. ## Prompt Examples **Prompt:** ``` Calculate the tax base for a product worth 100.00 with an 18% tax rate. ``` **Response:** ``` The `calculate_tax_base` tool would return a tax base of approximately 121.95 and a tax amount of 21.95. ``` **Prompt:** ``` What is the interstate rate for a shipment from Southeast to North region? ``` **Response:** ``` Using `get_interstate_rate` with origin 'Southeast' and destination 'North', the tool returns a rate of 7%. ``` **Prompt:** ``` Calculate DIFAL for a product worth 500.00, with an interstate rate of 12% and destination internal rate of 18%. ``` **Response:** ``` The `calculate_tax_differential` tool calculates a DIFAL amount of 30.00. ``` ## Capabilities ### Determine Applicable Rates Identify the correct tax rate by inputting the starting and ending regions of the shipment. ### Calculate Tax Base Value Compute the grossed-up product value required for 'inside' calculation methods. ### Determine Tax Substitution (ST) Calculate the precise amount of ICMS-ST that must be collected during a transaction. ### Compute Tax Differential (DIFAL) Figure out the required tax differential for any B2C interstate operation. ## Use Cases ### Handling B2C interstate sales A seller ships goods from São Paulo to Rio de Janeiro. They need to know the exact tax differential (DIFAL) owed. By using `get_interstate_rate` first, then running `calculate_tax_differential`, they generate a precise filing amount that matches state law. ### Auditing product cost valuation A corporate finance team needs to validate the listed price of a complex item. They run `calculate_tax_base` on the current sale data, confirming if the grossed-up value aligns with what auditors expect. ### Filing manufacturer tax reports A factory needs to file ST documentation for a new product line. They use `calculate_icms_substitution` along with the raw data inputs, generating the required substitution amount for their quarterly filings. ## Benefits - Avoid costly miscalculations. Use `calculate_tax_differential` to get the exact DIFAL amount for B2C sales, preventing underreporting penalties. - Verify product values correctly. The `calculate_tax_base` tool determines the grossed-up value using the 'inside' method, which is essential for internal accounting records. - Ensure compliance across states. By calling `get_interstate_rate`, you retrieve the precise rate needed for any shipment between Brazilian regions. - Handle manufacturer filings easily. The `calculate_icms_substitution` tool computes ST amounts quickly, streamlining your tax documentation process. - Reduce manual effort by automating complex math. Instead of building multi-step formulas in a spreadsheet, this MCP executes the entire calculation chain instantly. ## How It Works The bottom line is that it structures a multi-layered calculation process into one simple workflow. 1. First, define your transaction details and specify both the origin and destination regions. 2. Next, use these inputs to calculate the necessary rates or specific tax components (ST, DIFAL) based on current law. 3. Finally, you receive the exact calculated figure needed for compliant filing and ledger posting. ## Frequently Asked Questions **How do I use calculate_tax_base for product valuation?** You supply the nominal value and the tax rate to `calculate_tax_base`. It returns the required grossed-up product value using the 'inside' calculation method, which is critical for accurate inventory cost tracking. **What is DIFAL? How does calculate_tax_differential work?** DIFAL (Tax Differential) is the tax owed in B2C interstate sales. Use `calculate_tax_differential` by supplying the transaction value and rate details, and it returns the exact differential amount needed for compliance. **I need to know the rates between my two states; should I use get_interstate_rate?** Yes. `get_interstate_rate` is the tool you need. Just give it the origin and destination regions, and it pulls the current statutory tax rate for that specific movement. **What if I also need ST calculated? Do I use calculate_icms_substitution?** That’s right. For Tax Substitution (ST), you must run `calculate_icms_substitution`. This function uses the MVA to determine the exact amount that needs to be collected for your filing. **What data inputs are mandatory for `calculate_tax_base`?** The tool requires three key pieces of information: the net product value, the tax rate percentage, and whether you want the final calculation to reflect the grossed-up or exclusive price. Providing these details ensures an accurate 'inside' method calculation. **If I use `get_interstate_rate` but provide incorrect origin or destination regions, what happens?** The system will return a specific validation error detailing which region codes are invalid. Always double-check your state abbreviations against the official Brazilian tax lists before running the rate check. **Does `calculate_tax_differential` only work for B2C interstate operations?** Yes, this MCP tool is strictly designed to calculate DIFAL amounts for Business-to-Consumer transactions across state lines. It will not process tax differentials for internal or B2B sales. **How do I properly use the Added Value Margin (MVA) when running `calculate_icms_substitution`?** The MCP needs you to provide the correct MVA percentage. This margin is critical because it determines how we calculate Tax Substitution; ensure the provided rate matches the product's classification. **How do I calculate the grossed-up product value?** Use the `calculate_tax_base` tool. You provide the net product value and the tax rate, and it returns the grossed-up base and the tax amount included in that base. **Can I calculate ICMS-ST with MVA?** Yes. The `calculate_icms_substitution` tool allows you to input the initial tax base, the MVA percentage, and the relevant interstate and internal rates to find the substitution amount. **How does the tool determine the interstate rate?** The `get_interstate_rate` tool checks the origin and destination regions. It applies 4% for imports, 7% for movements from South/Southeast to North/Northeast/Midwest, and 12% for all other interstate routes.