Spanish Vehicle Tax Valuation MCP Server

The Spanish Vehicle Tax Valuation MCP is a Model Context Protocol (MCP) server that provides structured access to Spanish vehicle tax valuation data, including 2025 average sale prices and depreciation rates for vehicles, boats, motorcycles, and transport means per Orden HAC/1484/2024. It allows AI models to query tax valuation references for Spanish property transfer, inheritance, gift, and special transport taxes.

🎉 Now available on PyPI! Install with a single command - no Python setup required.

🚀 Quick Start for Claude Desktop

Simple 2-Step Setup (No Python Required!)

Step 1: Install UV (One-Time Setup)

Windows - Open PowerShell and run:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux - Open Terminal and run:

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Configure Claude Desktop

1. Open your Claude Desktop configuration file:

   • Windows: Press Win+R, type %APPDATA%\Claude\claude_desktop_config.json, press Enter
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "spanish-vehicle-tax": {
      "command": "uvx",
      "args": ["--pre", "--from", "spanish_vehicle_tax_valuation_mcp", "spanish-vehicle-tax-mcp"]
    }
  }
}

Note: The --pre flag installs the beta version. Remove it once version 1.0 is released.

3. Save the file and restart Claude Desktop

4. Done! 🎉 You can now ask Claude about Spanish vehicle tax valuations

Example Questions

Try asking Claude:

• "What vehicle categories are available?"
• "Search for Toyota models from 2023"
• "Calculate the tax valuation for a 3-year-old BMW X5"
• "What's the depreciation rate for 5-year-old cars?"

---

Features

• Vehicle Categories: Query different types of vehicles (cars, motorcycles, trucks, boats, etc.)
• Vehicle Search: Search for vehicle models by make, year, and category
• Price Information: Access historical and current pricing data
• Depreciation Rates: Get official depreciation rates by vehicle category and age
• Tax Valuation: Calculate official tax valuations based on Spanish regulations
• Real-time Data: Connect to live API for up-to-date vehicle information

Available Tools

The MCP server exposes the following tools:

1. get_vehicle_categories

Get all available vehicle categories (cars, motorcycles, trucks, etc.).

2. search_vehicle_models

Search for vehicle models with optional filters:

• make: Vehicle manufacturer (e.g., "Toyota", "Honda")
• year: Model year (e.g., 2023, 2024)
• category_id: Filter by category
• page, per_page: Pagination options

3. get_vehicle_model_details

Get detailed information about a specific vehicle model by ID.

4. get_vehicle_prices

Get vehicle price information with optional filters for model and year.

5. get_depreciation_rates

Get official depreciation rates filtered by category, age, or effective year.

6. calculate_vehicle_tax_valuation (Primary Tool)

Calculate the official tax valuation for a vehicle:

• model_id: The vehicle model ID
• vehicle_age: Age in years
• valuation_year: Optional year for calculation

Returns original price, depreciation rate, and taxable value.

7. get_stored_valuations

Get previously calculated valuations from the database.

8. check_api_health

Check the health and availability of the backend API.

Example Queries

Once integrated with your client, you can ask:

• "What are the available vehicle categories?"
• "Search for Toyota models from 2023"
• "Calculate the tax valuation for a 3-year-old Toyota Corolla"
• "What's the depreciation rate for 5-year-old cars?"
• "Show me prices for model ID 42"

📚 Documentation

• Installation Guide - Setup and access instructions
• Azure Deployment - Deploy to Azure App Service
• Architecture - Technical architecture and design

🧪 Testing

Run the test suite:

# Test all endpoints
python tests/test_server.py

# Run pytest suite
pytest tests/

📁 Project Structure

spanish-vehicle-tax-valuation-mcp/
├── src/                    # Application source code
│   ├── app.py             # FastAPI wrapper for Azure
│   ├── server.py          # MCP server with 8 tools
│   ├── api_client.py      # HTTP client for backend API
│   └── config.py          # Configuration settings
├── tests/                  # Test files
│   ├── test_server.py     # Integration tests
│   └── test_api_client.py # Unit tests
├── docs/                   # Documentation
│   ├── INSTALL.md         # Installation guide
│   ├── AZURE_DEPLOY.txt   # Deployment guide
│   └── ARCHITECTURE.md    # Architecture docs
├── requirements.txt        # Python dependencies
└── README.md              # This file

🔗 Quick Start

1. Access Production Server: See docs/INSTALL.md
2. Deploy Your Own: See docs/AZURE_DEPLOY.txt
3. Local Development:

   pip install -r requirements.txt
   uvicorn src.app:app --reload --port 8000
   

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or contributions, please open an issue on GitHub