spanish-vehicle-tax-valuation-mcp 0.1.0b4
MCP server for Spanish Vehicle Tax Valuation API
Requires Python: >=3.10

# Spanish Vehicle Tax Valuation MCP Server

[![PyPI version](https://badge.fury.io/py/spanish-vehicle-tax-valuation-mcp.svg)](https://pypi.org/project/spanish-vehicle-tax-valuation-mcp/)

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
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux** - Open Terminal and run:
```bash
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:

```json
{
  "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](docs/INSTALL.md)** - Setup and access instructions
- **[Azure Deployment](docs/AZURE_DEPLOY.txt)** - Deploy to Azure App Service
- **[Architecture](docs/ARCHITECTURE.md)** - Technical architecture and design

## 🧪 Testing

Run the test suite:

```bash
# 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](docs/INSTALL.md)
2. **Deploy Your Own**: See [docs/AZURE_DEPLOY.txt](docs/AZURE_DEPLOY.txt)
3. **Local Development**: 
   ```bash
   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](https://github.com/sarguinsson/spanish-vehicle-tax-valuation-mcp/issues)