Avalara Returns MCP server

Overview

Provides access to the Avalara Global Returns API for tax returns management, filing calendars, and compliance data.

How to connect to MCP server

Returns MCP server does not use OAuth2 flow and requires a valid JWT Token.
The JWT Token can be generated using the License Key provided to the customer.
Once generated, paste the JWT Token into the MCP client configuration under the Authorization header.

Use the following JSON configuration for the MCP clients:

{
  "avalara-returns": {
    "transport": "http",
    "url": "https://mcp.avalara.com/returns",
    "headers": {
      "Authorization": "Bearer jwt_token_here"
    }
  }
}

MCP client setup

Cursor

Tools

Name	Description	Sample prompt
get_countries_returns	Provides a list of countries and regions supported by Managed Returns.	Provide all the countries Avalara supports in {country_name} for tax {tax_type}
get_tax_types_returns	Provides the tax types supported by Managed Returns.	What are the tax types supported by Avalara Managed Returns?
get_tax_forms_returns	Provides tax forms including codes, regions, and associated tax types supported by Managed Returns.	List all tax forms for {country_Id} or {region_Id} with their tax types.
get_filing_calendars_returns	Provides filing calendars for a given company ID from Managed Returns.	Get filing calendars for company id {company_Id}
get_suggested_tax_forms_returns	Provides automated tax form recommendations for a company based on transaction history, helping merchants identify which returns to file.	Get suggested tax forms for company ID {companyId}.
create_company_returns	Create a company under a client account for managing multiple legal entities with separate tax obligations. Each company represents a distinct legal entity for jurisdictional requirements, filing calendars, and return submissions.	Create a company with account ID {accountId}, name "{companyName}", country "{country}", company code "{companyCode}", taxpayer ID "{taxpayerId}", and contact details including city, region, address, email, and phone
create_and_link_account_returns	Creates a Avalara client account under the partner firm, creates a default company profile, and generates client credentials, serving as the first step in onboarding a new merchant.	Create and link a new client account for {accountName} with address {address}, company code {companyCode}, and contact {firstName} {lastName}
create_firm_client_linkage_returns	Provides a way to link an existing client account to a firm in Avalara Managed Returns using the firm account ID and firm name, establishing a formal relationship for managing tax returns when the client already has an Avalara account.	Link existing client account to firm account ID {firmAccountId} with name '{firmAccountName}'.
get_filing_cal_req_setup_returns	Provides the setup template and required questions for creating a filing calendar request for a specific tax form and company.	Get filing calendar request setup model for tax form {taxFormCode} for company ID {companyId}.
create_filing_cal_req_returns	Create and submit a filing calendar request for approval. This request does not create a filing calendar directly; the actual filing calendar is automatically generated by Avalara once the request is approved.	Create filing calendar request for company ID {companyId} with tax form {taxFormCode}, frequency {frequencyCode}, and effective date {effDate}.
get_filing_cal_req_status_returns	Provides the status of filing calendar requests for a company.	Get filing calendar requests status for company ID {companyId}.
get_revenue_transactions_mylodge	Provides revenue transactions for a MyLodge property within a specified date range.	Get MyLodge revenue transactions for location {locationId} from {startDate} to {endDate}.
get_tax_summaries_mylodge	Provides tax summaries for a MyLodge property, optionally filtered by marketplace.	Get MyLodge lodging property tax summaries for location {locationId} in {marketplace}.
get_tax_details_mylodge	Provides detailed tax information for a MyLodge property, optionally filtered by marketplace.	Get MyLodge lodging property tax details for location {locationId} in {marketplace}.
get_customer_locations_mylodge	Fetch customer locations for a mylodge customer.	Get MyLodge lodging customer locations for customer {customerId}.
get_return_tracker_propertytax	Provides return tracking data from the Property Tax API for assessor accounts. Supports filtering by assessor, tax year, state, client name, account type, return status, deadlines, and work groups. Returns property tax return details, including deadlines, values, and processing status. Filtering occurs on the server after data retrieval. If no records match the current batch, the response may be empty while additional data is available. Use skip/take pagination and increment skip values until nextPage returns null to retrieve all matching results.	Get the Property Tax return tracker for assessor {assessorName} in tax year {year} with return status {status} and deadline after {date}.
get_assessment_tracker_propertytax	Provides assessment tracking data from the Property Tax API for assessor accounts. Supports filtering by assessor, tax year, state, client name, account type, notice and appeal status, deadlines, hearing dates, appeal manager, and work groups. Returns property tax assessment details, including notices, appeals, values, and processing status. Filtering occurs on the server after data retrieval. If no records match the current batch, the response may be empty while additional data is available. Use skip/take pagination and increment skip values until nextPage returns null to retrieve all matching results.	Get the Property Tax assessment tracker for assessor {assessorName} in tax year {year} with notice status {status} and appeal deadline before {date}
get_countries_returns_vat	Provides a list of countries and regions supported by VAT Returns.	Provide all the countries and regions in VAT Returns.
get_tax_types_returns_vat	Provides the tax types supported by VAT Returns.	What are the tax types supported by VAT Returns?
get_tax_forms_returns_vat	Provides tax forms including codes, regions, and associated tax types supported by VAT Returns.	List all tax forms for {country_Id} and {region_Id} with their tax types in VAT Returns.
create_client_returns_vat	Creates a new client in VAT Returns.	Create a new client in VAT Returns with name "{clientName}".
get_jurisdictions_excise	Provides a list of jurisdictions licensed for Returns for the requesting company and user, based on data from the Excise platform.	Get licensed Excise jurisdictions for company "{companyName}" in country "{countryCode}".
get_taxpayer_types_excise	Provides a list of licensed taxpayer types for a given jurisdiction and country of a specific company and user from the Excise platform.	Get Excise taxpayer types for company "{companyName}" in jurisdiction "{jurisdiction}" and country "{countryCode}".
import_business_entities_excise	Provides a way to import business entities and associated business accounts into the Excise platform for the specific company and user. Supports batch import with options to update existing records or skip matches.	Import business entities for company "{companyName}" with trade name "{tradeName}" and license number "{licenseNumber}" in jurisdiction "{jurisdiction}".
import_locations_excise	Provides a way to import locations into the Excise platform for the specific company and user. Supports batch import with options to update existing records, perform exact field matching, or terminate new records.	Import locations for company "{companyName}" with terminal code "{terminalCode}" in city "{city}", jurisdiction "{jurisdiction}".