Voice
Tax Calculator
By OpenClaw MCP Plugin for multi-country tax calculation, compliance, and invoice generation for e-commerce
Install
npm install
#Configuration Example
{
"mcpServers": {
"tax-calculator": {
"command": "node",
"args": ["/path/to/tax-calculator-plugin/src/index.js"],
"env": {
"TAXJAR_API_KEY": "${env:TAXJAR_API_KEY}",
"AVALARA_ACCOUNT_ID": "${env:AVALARA_ACCOUNT_ID}"
}
}
}
}README
# Tax Calculator MCP Plugin
OpenClaw MCP Plugin for cross-border e-commerce tax calculation, rate lookup, compliance checking, and invoice generation.
## Features
- **Multi-country Tax Calculation**: Calculate VAT, GST, sales tax for 50+ countries
- **Tax Rate Lookup**: Get current and historical tax rates by jurisdiction
- **Address Validation**: Validate addresses and determine tax jurisdiction
- **Nexus Determination**: Determine tax nexus (physical, economic, digital)
- **Tax Invoice Generation**: Generate tax-compliant invoices in JSON, HTML, PDF, or text format
- **Compliance Checking**: Check tax compliance requirements for businesses
- **Liability Estimation**: Estimate tax liability for reporting periods
- **Filing Requirements**: Get filing requirements and deadlines
## Supported Tax Systems
- **EU VAT**: All 27 EU member states + UK
- **US Sales Tax**: All 50 states with economic nexus thresholds
- **Canada GST/HST/PST**: Federal and provincial taxes
- **Australia GST**: Goods and Services Tax
- **New Zealand GST**: Goods and Services Tax
- **Singapore GST**: Goods and Services Tax
- **Japan Consumption Tax**
- **Digital Services Taxes**: Multiple jurisdictions
## Tools
### Core Tools (8 required functions)
1. **tax_calculate_amount** - Calculate tax amount for a transaction
2. **tax_get_rate** - Get tax rate for specific jurisdiction and product category
3. **tax_validate_address** - Validate address and determine tax jurisdiction
4. **tax_determine_nexus** - Determine tax nexus for business in jurisdiction
5. **tax_generate_invoice** - Generate tax-compliant invoice with breakdown
6. **tax_check_compliance** - Check tax compliance requirements
7. **tax_estimate_liability** - Estimate tax liability for period
8. **tax_get_filing_requirements** - Get tax filing requirements
### Additional Tools
9. **tax_get_provider_status** - Get status of tax calculation providers
## Architecture
### Multi-provider Strategy
- **Primary**: TaxJar API (comprehensive sales tax calculation)
- **Secondary**: Avalara API (enterprise tax automation)
- **Fallback**: Local rules engine with 50+ countries
### Intelligent Fallback
- 30-day cache for tax rates
- 90-day cache for tax rules
- Automatic provider switching on failure
- Offline-capable local rule engine
### E-commerce Optimization
- EU VAT MOSS (Mini One Stop Shop) support
- US economic nexus tracking
- Digital goods tax calculation
- B2B reverse charge handling
## Installation
```bash
# Clone the repository
git clone https://github.com/aoyasong/tax-calculator-plugin.git
cd tax-calculator-plugin
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env
# Edit .env with your API keys
# Run tests
npm test
# Start the plugin
npm start
```
## Configuration
### Environment Variables
```bash
# API Keys
TAXJAR_API_KEY=your_taxjar_api_key
AVALARA_ACCOUNT_ID=your_avalara_account_id
AVALARA_LICENSE_KEY=your_avalara_license_key
# Cache Settings
REDIS_ENABLED=false
REDIS_URL=redis://localhost:6379
# Rate Limiting
REQUEST_LIMIT_PER_MINUTE=30
# Compliance Settings
DISCLAIMER_ENABLED=true
AUDIT_LOGGING=false
# Data Paths
LOCAL_RULES_PATH=./data
```
### MCP Configuration
Add to your OpenClaw configuration:
```json
{
"mcpServers": {
"tax-calculator": {
"command": "node",
"args": ["/path/to/tax-calculator-plugin/src/index.js"],
"env": {
"TAXJAR_API_KEY": "${env:TAXJAR_API_KEY}",
"AVALARA_ACCOUNT_ID": "${env:AVALARA_ACCOUNT_ID}"
}
}
}
}
```
## Usage Examples
### Calculate US Sales Tax
```javascript
// Calculate 7.25% sales tax for a $100 purchase in California
const result = await tax_calculate_amount({
amount: 100,
currency: "USD",
from_country: "US",
to_country: "US",
region_code: "CA",
transaction_type: "b2c",
customer_type: "individual",
product_category: "electronics"
});
```
### Check EU VAT Compliance
```javascript
// Check if a digital services business needs to register for VAT in Germany
const compliance = await tax_check_compliance({
country: "DE",
transaction_type: "digital_services",
business_size: "small",
annual_turnover_usd: 50000,
registration_status: "not_registered"
});
```
### Generate Tax Invoice
```javascript
// Generate a tax-compliant invoice in HTML format
const invoice = await tax_generate_invoice({
transaction_id: "TXN-12345",
date: "2026-03-20",
business: {
name: "Electronics Store",
tax_id: "US123456789",
address: "123 Business St, CA",
country: "US"
},
customer: {
name: "John Smith",
address: "456 Consumer Ave, CA",
country: "US",
type: "individual"
},
items: [
{
description: "Wireless Headphones",
quantity: 2,
unit_price: 50,
product_category: "electronics"
}
],
format: "html"
});
```
## Integration with Other Plugins
### E-commerce Database Plugin
- Store transaction tax records
- Track historical tax calculations
- Maintain audit trails
### Currency Exchange Plugin
- Multi-currency tax calculations
- Exchange rate integration for cross-border taxes
### Amazon SP-API Plugin
- Amazon marketplace tax calculation
- FBA inventory tax implications
### Finance Agent
- Tax liability reporting
- Financial statement tax sections
## Data Sources
### External APIs
- **TaxJar**: Real-time sales tax rates for US, CA, AU, EU
- **Avalara**: Enterprise-grade tax calculation and compliance
### Local Data
- Core country tax rates and thresholds
- EU VAT rules and MOSS procedures
- US state economic nexus thresholds
- Digital services tax rules
## Caching Strategy
- **Tax Rates**: 30-day cache (industry standard update frequency)
- **Tax Rules**: 90-day cache (regulations change quarterly)
- **Address Validation**: 365-day cache (jurisdictions rarely change)
- **Memory Cache**: Primary cache layer
- **Redis Cache**: Optional distributed cache for multi-instance deployments
## Compliance & Disclaimer
### Important Notice
This plugin provides **tax estimations only**. It is not a substitute for professional tax advice.
### Key Limitations
- Rates may be outdated or inaccurate
- Local jurisdiction rules vary widely
- Tax laws change frequently
- Special exemptions may apply
### Recommended Usage
1. Use for estimation and planning
2. Verify with official tax authorities
3. Consult with qualified tax professionals
4. Maintain audit trails of all calculations
## Development
### Project Structure
```
src/
├── index.js # Main entry point
├── tax-api.js # Main API client
├── tools.js # MCP tool definitions
├── providers/ # External API providers
│ ├── taxjar-api.js
│ ├── avalara-api.js
│ └── local-rules.js
├── rules/ # Tax rule engines
│ ├── tax-calculator.js
│ ├── compliance-checker.js
│ └── nexus-detector.js
├── models/ # Data models
│ ├── tax-rate.js
│ ├── jurisdiction.js
│ └── transaction.js
├── utils/ # Utilities
│ ├── errors.js
│ └── validation.js
└── cache/ # Caching modules
├── memory-cache.js
└── redis-cache.js
```
### Testing
```bash
# Run unit tests
npm test
# Run integration tests
npm run test:integration
# Run with coverage
npm run test:coverage
```
### Adding New Jurisdiction
1. Add country rules to `src/rules/country-rules.js`
2. Add tax rate data to `data/tax-rates-{COUNTRY}.json`
3. Update local rules provider mapping
4. Add test cases
## License
MIT License - see LICENSE file for details.
## Support
- GitHub Issues: https://github.com/aoyasong/tax-calculator-plugin/issues
- Email: [email protected]
**Disclaimer**: This software is provided "as is" without warranty of any kind. The authors are not responsible for any tax liabilities incurred through use of this software.
voice
Comments
Sign in to leave a comment