Car2db Api V3 MCP

🚀 Car2DB MCP Server

The MCP (Model Context Protocol) server for Car2DB API v3, enabling LLM agents (Claude, ChatGPT, Cursor, VSCode) to directly interact with the automotive database.

✨ Features

• Complete Vehicle Database — Access detailed specifications for cars, motorcycles, and trucks.
• Smart Search — Conduct natural language vehicle searches.
• Rich Data — Obtain technical specs, equipment packages, and detailed characteristics.
• Multi - language — Support for 11 languages.
• Dual Transport — stdio (Claude Desktop/Cursor) and SSE (remote access).
• Docker Ready — Production - ready containerization.

🚀 Quick Start

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "car2db": {
      "command": "npx",
      "args": ["-y", "@car2db/mcp-server"],
      "env": {
        "CAR2DB_API_KEY": "your_api_key_here",
        "CAR2DB_REFERER": "https://yourproject.com",
        "CAR2DB_LANGUAGE": "en-US"
      }
    }
  }
}

Get your API key: https://car2db.com/api/
Try demo key: https://car2db.com/api-token-demo/

GitHub Copilot Configuration

For GitHub Copilot, use the .vscode/mcp.json configuration file in your project:

{
  "servers": {
    "car2db": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "CAR2DB_API_KEY": "your_api_key_here",
        "CAR2DB_REFERER": "https://yourproject.com",
        "CAR2DB_LANGUAGE": "en-US",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Or use npx for zero - install:

{
  "mcpServers": {
    "car2db": {
      "command": "npx",
      "args": ["-y", "@car2db/mcp-server"],
      "env": {
        "CAR2DB_API_KEY": "your_api_key_here",
        "CAR2DB_REFERER": "https://yourproject.com",
        "CAR2DB_LANGUAGE": "en-US"
      }
    }
  }
}

Get your API key: https://car2db.com/api/
Try demo key: https://car2db.com/api-token-demo/

📦 Installation Options

1. MCPB Package (One - Click Install)

Download the pre - built MCPB extension for easy installation in Claude Desktop or other MCP clients: [Download car2db - api - v3 - mcp.mcpb](https://github.com/car2db/car2db - api - v3 - mcp/releases/latest/download/car2db - api - v3 - mcp.mcpb)

MCPB is a ZIP archive containing a local MCP server and manifest.json describing the server and its capabilities. Just download and install with one click.

Installation Steps:

1. Download the .mcpb file from GitHub releases.
2. Double - click the file or drag it into your MCP client.
3. Configure your API key in the setup dialog (optional, demo key will be used if not provided).
4. Click "Install" and start using the extension.

GitHub Releases: [https://github.com/car2db/car2db - api - v3 - mcp/releases](https://github.com/car2db/car2db - api - v3 - mcp/releases)

2. npx (Zero Install)

npx @car2db/mcp-server

3. Global npm Installation

npm install -g @car2db/mcp-server
car2db-mcp

4. Local Development

git clone https://github.com/car2db/car2db - api - v3 - mcp.git
cd car2db - api - v3 - mcp
npm install
npm run build
npm start

5. Docker (for SSE mode)

docker-compose up -d

Or manually:

docker build -t car2db-mcp .
docker run -p 3000:3000 \
  -e CAR2DB_API_KEY=your_key \
  -e CAR2DB_REFERER=https://yourproject.com \
  car2db-mcp

📚 Documentation

Environment Variables

Referer header

The Car2DB API requires a Referer header in every request. Set CAR2DB_REFERER to the URL of the project or site that uses this MCP server. This URL must match the one registered with your API key on car2db.com.

If CAR2DB_REFERER is not set, a warning is printed at startup and API requests will fail with 403 Forbidden.

Example .env file

CAR2DB_API_KEY=your_api_key_here
CAR2DB_REFERER=https://yourproject.com
CAR2DB_LANGUAGE=en-US
MCP_TRANSPORT=stdio

Available Tools

Smart Tools (High - Level)

Low - Level Tools (Direct API Access)

Tool Parameters Reference

• typeId: Vehicle type filter
  • 1 = Cars
  • 2 = Motorcycles
  • 3 = Trucks
• page: Page number (default: 1)
• itemsPerPage: Items per page (default: 30)

💻 Usage Examples

Example 1: Find specific vehicle specifications

Claude: "What are the specifications of 2020 BMW X5 xDrive40i?"

Agent workflow:
1. search_vehicles(q: "BMW X5 xDrive40i 2020")
2. get_trim_full(trimId: <from_search_results>)
3. Returns: breadcrumbs, key specs, full specifications, available equipments

Example 2: Compare equipment packages

Claude: "Compare equipment packages for Toyota Camry 2023"

Agent workflow:
1. search_vehicles(q: "Toyota Camry 2023")
2. get_trim_full(trimId: ...) → get equipment list
3. get_equipment_full(equipmentId: A) → package A options
4. get_equipment_full(equipmentId: B) → package B options
5. Compare and present differences

Example 3: Browse catalog

Claude: "Show me all Tesla models"

Agent workflow:
1. browse_catalog(level: "makes") → find Tesla
2. browse_catalog(level: "models", makeId: 56) → all Tesla models
3. browse_catalog(level: "trims", modelId: 789) → trims for Model 3

Example 4: Year - based search

Claude: "What electric SUVs were available in 2024?"

Agent workflow:
1. get_year_vehicles(year: 2024, typeId: 1)
2. Filter for electric powertrains
3. Filter for SUV body types
4. Present results

🔧 Technical Details

SSE Mode (Remote Access)

For remote access or integration with web services, use SSE transport:

Start SSE Server

export MCP_TRANSPORT=sse
export MCP_SSE_PORT=3000
npm start

Or with Docker:

docker-compose up -d

SSE Endpoints

• SSE Connection: GET http://localhost:3000/sse
• Messages: POST http://localhost:3000/messages
• Health Check: GET http://localhost:3000/health

API Coverage

This MCP server provides access to Car2DB API v3 endpoints:

• /search/vehicles — Vehicle search
• /makes — Manufacturers list
• /models — Vehicle models
• /generations — Model generations
• /series — Body style series
• /trims — Engine/transmission trims
• /trims/{id}/full — Complete trim data
• /equipments/{id}/full — Equipment packages
• /years/{year} — Vehicles by year

Base URL: https://v3.api.car2db.com

Development

Build

npm run build

Type Check

npm run typecheck

Development Mode

npm run dev

📄 License

This project is licensed under the MIT License.

📎 Links

• Repository: [https://github.com/car2db/car2db - api - v3 - mcp](https://github.com/car2db/car2db - api - v3 - mcp)
• npm Package: [https://www.npmjs.com/package/@car2db/mcp - server](https://www.npmjs.com/package/@car2db/mcp - server)
• Car2DB API: https://car2db.com/api/
• Model Context Protocol: https://modelcontextprotocol.io/

🛠️ Support

For API - related questions and support:

• Email: support@car2db.com
• Website: https://car2db.com
• Telegram: https://t.me/car2db_support_bot

For MCP server issues:

• GitHub Issues: [https://github.com/car2db/car2db - api - v3 - mcp/issues](https://github.com/car2db/car2db - api - v3 - mcp/issues)

⚙️ Requirements

• Node.js >= 20.0.0
• Valid Car2DB API key

🔑 Get API Access

• Purchase API Key: https://car2db.com/api/
• Try Demo Key: [https://car2db.com/api - token - demo/](https://car2db.com/api - token - demo/)
• API Documentation: https://v3.api.car2db.com/docs