🚗 CarsXE MCP Server

A modular, extensible Model Context Protocol (MCP) server for querying and analyzing vehicle data from CarsXE, with beautiful, chat-friendly Markdown output for LLMs and chatbots.

Products

• Vehicle History
• Vehicle Plate Decoder
• Vehicle Specifications
• International VIN Decoder
• Vehicle Images
• Vehicle Recalls
• Vehicle Market Value

ℹ️ What is CarsXE MCP Server?

The CarsXE MCP server is a Node.js/TypeScript application that exposes a suite of tools for querying comprehensive vehicle data from CarsXE. It is designed for seamless integration with LLMs (like Anthropic Claude, OpenAI GPT, etc.), chatbots, and developer tools, providing:

• 🧩 Clean, modular code for each CarsXE endpoint
• 📝 Consistent, Markdown-rich output for chat/LLM environments
• 🛡️ Robust error handling and user-friendly messages
• 🔌 Easy extensibility for new endpoints and features

💡 Why Use CarsXE with MCP?

Connecting CarsXE to your AI editor or chat client via MCP gives you a supercharged vehicle data experience — directly inside the tools you already use:

✨ Features

• 🤖 Uses Anthropic Claude to generate comprehensive, professional answers based on the API data and user query
• 🚙 Query vehicle specs, history, images, recalls, market value, and more
• 🏷️ Decode license plates and international VINs (including OCR from images)
• 🛠️ Decode OBD (On-Board Diagnostics) codes
• 🎨 All endpoints return elegant, grouped, emoji-rich Markdown
• 🧩 ChatGPT / MCP Apps hosts can render vehicle, market-value, and recall cards via dedicated render tools
• 🧑‍💻 Modular code: types, API logic, and formatters are separated for maintainability
• 🧪 Simple to run, test, and extend

⚙️ Prerequisites

CarsXE API key (get one here)

🖥️ Installation by Editor

All editors use the same remote MCP endpoint. Replace YOUR_API_KEY with your actual CarsXE API key in every config below.

Cursor Marketplace / Grok Bot

After listing, install CarsXE from the Cursor Marketplace (Grok Bot uses the same catalog). Then open Plugins → Configure and set CARSXE_API_KEY from the CarsXE developer dashboard. Do not commit or paste a real key into the repo.

The Cursor deeplink below remains available as a fallback.

Claude Desktop

1️⃣ Download and Install Claude Desktop

• Go to the official Claude Desktop download page
• Download the installer for your operating system (macOS, Windows, or Linux)
• Install Claude Desktop by following the on-screen instructions

2️⃣ Configure Claude Desktop to Use the CarsXE MCP Server

a. Open Claude Desktop Settings

• Launch the Claude Desktop app
• Click on Claude in the menu bar
• Select Settings
• In the Settings window, go to the Developer tab (you may need to scroll or expand advanced options)
• Click Edit Config (or Open Config File)

b. Edit the Configuration File

• This will open the claude_desktop_config.json file in your default text editor.

• Locate the "mcpServers" section. If it does not exist, add it as shown below.

• Add or update the following entry for CarsXE:

  json

  "mcpServers": {
    "carsxe": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.carsxe.com/mcp",
        "--header",
        "X-API-Key: YOUR_API_KEY"
      ]
    }
  },
  

• Replace YOUR_API_KEY with your actual CarsXE API Key

• Tip: You can add multiple MCP servers under "mcpServers" if you use more than one.

• Save the configuration file and close your editor.

c. Restart Claude Desktop

• Close and reopen the Claude Desktop app to apply the new configuration.

  It may take a short delay for the changes to take effect.

3️⃣ Verify the CarsXE MCP Server is Available

• After restarting, open Claude Desktop.
• Go to the tools or plugins section (usually in the search bar or under a tools menu).
• You should see CarsXE listed as an available MCP server/tool.
• Try running a CarsXE tool (e.g., get_vehicle_specs) to verify everything is working.

  This will only work if your API key is associated with an active subscription.

Cursor

Fallback if the marketplace listing is not available yet:

Install CarsXE MCP for Cursor

The install dialog will open pre-filled with:

Replace YOUR_API_KEY with your actual CarsXE API key, then click Install.

Visual Studio Code (GitHub Copilot)

Install CarsXE MCP for VS Code

After clicking install, you'll need to add your API key manually:

1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run MCP: List Servers
3. Find CarsXE in the list and click on it
4. Click Show Configuration
5. Replace YOUR_API_KEY with your actual CarsXE API key:

   "CarsXE": {
     "type": "http",
     "url": "https://mcp.carsxe.com/mcp",
     "headers": {
       "X-API-Key": "YOUR_ACTUAL_KEY_HERE"
     }
   }

6. Save the file — VS Code will connect automatically.

Note: Make sure you have the GitHub Copilot extension installed and agent mode enabled (chat.agent.enabled in VS Code settings).

Windsurf

1️⃣ Open MCP Configuration

• Go to Windsurf Settings → MCP (or press Ctrl+, and search for MCP)
• Click "Edit Config" to open ~/.codeium/windsurf/mcp_config.json

2️⃣ Add the CarsXE Server

{
  "mcpServers": {
    "carsxe": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.carsxe.com/mcp",
        "--header",
        "X-API-Key: YOUR_API_KEY"
      ]
    }
  }
}

3️⃣ Restart Windsurf

Reload the window or restart Windsurf. Open the Cascade chat panel — CarsXE tools will appear automatically.

Other Editors (Manual / Generic)

For any other MCP-compatible client, register a remote MCP server using:

• Endpoint: https://mcp.carsxe.com/mcp
• Transport: HTTP (Streamable HTTP)
• Auth header: X-API-Key: YOUR_API_KEY

Consult your editor's MCP documentation for the exact configuration format.

🖼️ ChatGPT / MCP Apps UI (data → render)

Hosts that implement MCP Apps (including ChatGPT) can show inline vehicle cards. CarsXE keeps fetch tools as data tools and mounts UI only from dedicated render tools, so ChatGPT does not remount an iframe on every lookup.

Recommended call flow:

1. Call a data tool (get_vehicle_specs, get_market_value, or get_vehicle_recalls). It returns Markdown plus structuredContent — no _meta.ui.resourceUri.
2. The model may refine that structured result.
3. Call the matching render tool (render_vehicle_card, render_market_value, or render_recalls) with those fields.
4. The host loads the ui://carsxe/… HTML resource (text/html;profile=mcp-app) and renders the card once.

Cards use published tokens from @carsxe/design-system (--primary #065774, --background #F9F9F9, --card #FFFFFF, rounded-2xl chrome) and the official Logo assets https://ui.carsxe.com/logo-light.png / logo-dark.png.

Auth is unchanged: MCP still requires an API key or OAuth. x402 remains REST-only.

Preview the cards locally (no API key, mock data):

npm run preview:ui

Then open previews/vehicle-card.html, previews/market-value.html, and previews/recalls.html in a browser.

🛠️ Available Tools & Example Prompts

Below is a list of all available CarsXE tools, their parameters, and example prompts. These prompts work in any MCP-connected client.

1. get_vehicle_specs 🚙

• Description: Get comprehensive vehicle specifications by VIN (Vehicle Specifications)

• Parameters:

  • vin (string, required): 17-character Vehicle Identification Number

• Example Prompts:

  What are the full specs for VIN WBAFR7C57CC811956?

  Is this a V6 or V8? VIN: WBAFR7C57CC811956

  What trim level is WBAFR7C57CC811956?

• Output: Markdown-formatted vehicle specs (year, make, model, engine, dimensions, colors, equipment, etc.)

2. decode_license_plate 🏷️

• Description: Decode a vehicle's license plate to get VIN and basic info (Vehicle Plate Decoder)

• Parameters:

  • plate (string, required): License plate number
  • state (string, optional): State abbreviation (e.g., CA)
  • country (string, required, default: US): Country code

• Example Prompts:

  What car has license plate 7XER187 in California?

  Decode plate 7XER187 state CA

  Look up the plate ABC1234 in Texas

• Output: Markdown summary of decoded vehicle info (VIN, make, model, year, etc.)

3. decode_international_vin 🌍

• Description: Decode an international VIN for detailed info (International VIN Decoder)

• Parameters:

  • vin (string, required): 17-character VIN

• Example Prompts:

  Decode this European VIN: WF0MXXGBWM8R43240

  What car is WAUZZZ8K9AA123456? It's a German VIN.

• Output: Markdown with international vehicle details (manufacturer, specs, emissions, etc.)

4. get_market_value 💰

• Description: Get estimated market value for a vehicle by VIN (Vehicle Market Value)

• Parameters:

  • vin (string, required): 17-character VIN
  • state (string, optional): US state abbreviation
  • mileage (number, optional): Current mileage of the vehicle to adjust the market value
  • condition (string, optional): Overall condition of the vehicle — excellent, clean, average, or rough

• Example Prompts:

  How much is WBAFR7C57CC811956 worth?

  I'm thinking of buying VIN WBAFR7C57CC811956 — what's a fair price?

  What's the trade-in value for WBAFR7C57CC811956 in Florida with 45,000 miles in clean condition?

• Output: Markdown with market value breakdown (retail, trade-in, MSRP, etc.)

5. get_vehicle_history 🕓

• Description: Get a comprehensive vehicle history report by VIN (Vehicle History)

• Parameters:

  • vin (string, required): 17-character VIN
  • format (string, optional): Response format (json or xml)

• Example Prompts:

  Has WBAFR7C57CC811956 ever been in an accident?

  Show me the full history for VIN WBAFR7C57CC811956

  How many owners has WBAFR7C57CC811956 had?

• Output: Markdown with history records (junk/salvage, insurance, brands, titles, odometer, etc.)

6. get_vehicle_images 🖼️

• Description: Get vehicle images by make, model, and filters (Vehicle Images)

• Parameters:

  • make (string, required)
  • model (string, required)
  • year, trim, color, transparent, angle, photoType, size, license, format (all optional)

• Example Prompts:

  Show me photos of a blue 2018 Toyota Tacoma

  Get images of a red 2022 Ford Mustang GT

  What does a white 2020 Tesla Model 3 look like?

• Output: Markdown with up to 5 images (links, thumbnails, details)

7. get_vehicle_recalls 🚨

• Description: Get vehicle recall information by VIN (Vehicle Recalls)

• Parameters:

  • vin (string, required): 17-character VIN

• Example Prompts:

  Does 1C4JJXR64PW696340 have any open recalls?

  I just bought VIN 1C4JJXR64PW696340 — should I be worried about recalls?

  Check for safety recalls on WBAFR7C57CC811956

• Output: Markdown with recall details (date, description, risk, remedy, status, etc.)

8. read_license_plate_from_image 🏷️

• Description: Recognize and extract license plate(s) from a vehicle image URL (Vehicle Plate Decoder)

• Parameters:

  • imageUrl (string, required): Direct URL to an image of a vehicle's license plate

• Example Prompts:

  What's the plate number in this image? https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public

  Read the license plate from this photo: [image URL]

• Output: Markdown with detected plates, confidence scores, bounding boxes, vehicle type, etc.

9. extract_vin_from_image 🔍

• Description: Extract the VIN from a vehicle image using OCR

• Parameters:

  • imageUrl (string, required): Direct URL to an image of a vehicle's VIN

• Example Prompts:

  Extract the VIN from this image: https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png

  What's the VIN in this photo? https://res.cloudinary.com/carsxe/image/upload/q_auto/f_auto/v1713204144/base/images/vin-ocr/vin.jpg

• Output: Markdown with detected VIN, confidence, bounding box, and candidates

10. get_year_make_model 📅

• Description: Get comprehensive vehicle info by year, make, model, and optional trim (Vehicle Specifications)

• Parameters:

  • year (string, required)
  • make (string, required)
  • model (string, required)
  • trim (string, optional)

• Example Prompts:

  What are the specs for a 2020 Toyota Camry?

  Tell me about the 2019 Honda Civic Sport trim

  What colors were available on the 2021 Ford F-150?

• Output: Markdown with vehicle details, colors, features, options, and packages

11. decode_obd_code 🛠️

• Description: Decode an OBD code and get diagnosis information

• Parameters:

  • code (string, required): OBD code (e.g., P0115)

• Example Prompts:

  My check engine light is on with code P0115 — what does it mean?

  Decode OBD code P0300

  I have a C1234 code on my dashboard — is it serious?

• Output: Markdown with code, diagnosis, and date

12. check_lien_and_theft 🔒

• Description: Get lien and theft information for a vehicle by VIN

• Parameters:

  • vin (string, required): 17-character Vehicle Identification Number

• Example Prompts:

  Is there a lien on WBAFR7C57CC811956?

  I'm buying a used car with VIN WBAFR7C57CC811956 — check if it's stolen

  Verify the title is clean for WBAFR7C57CC811956

• Output: Markdown with lien holder information, theft records, recovery dates, and status

13. get_recalls_by_ymm 🚨

• Description: Get safety recall information by year, make, and model (no VIN required) (Vehicle Recalls)

• Parameters:

  • year (string, required): 4-digit model year
  • make (string, required)
  • model (string, required)

• Example Prompts:

  Are there any recalls on a 2026 Toyota Corolla?

  Check safety recalls for a 2019 Honda Civic

  What recalls affect 2020 Ford F-150s?

• Output: Markdown with NHTSA campaign numbers, components, risk, and remedies

14. submit_recalls_batch 📦

• Description: Submit an async bulk recall check for up to 10,000 VINs (Vehicle Recalls)

• Parameters:

  • vins (string[] or comma-separated string, optional)
  • csv (string, optional): inline CSV of VINs
  • csvUrl (string, optional): HTTPS URL to a CSV of VINs
  • webhookUrl (string, optional): HTTPS webhook when the batch finishes

• Example Prompts:

  Submit a recalls batch for VINs 1HGBH41JXMN109186, 5YJSA1E26HF000001, and 1C4JJXR64PW696340

  Start a bulk recall check from this CSV URL: https://example.com/vins.csv

• Output: Markdown with batchId and status. Poll get_recalls_batch_status next.

15. get_recalls_batch_status 📦

• Description: Check the status of a previously submitted recalls batch (Vehicle Recalls)

• Parameters:

  • batchId (string, required)

• Example Prompts:

  What's the status of recalls batch brb_mnablbn7_wvbaqv?

• Output: Markdown with status, processed VIN counts, and hit rate

16. get_recalls_batch_results 📦

• Description: Fetch completed bulk recall results as JSON (after status is completed or partial) (Vehicle Recalls)

• Parameters:

  • batchId (string, required)

• Example Prompts:

  Get the recall results for batch brb_mnablbn7_wvbaqv

• Output: Markdown summary per VIN (truncated for large batches)

17. download_recalls_batch 📦

• Description: Download completed bulk recall results as CSV (Vehicle Recalls)

• Parameters:

  • batchId (string, required)

• Example Prompts:

  Download the CSV for recalls batch brb_mnablbn7_wvbaqv

• Output: Markdown preview of the CSV

18. get_ymm_options 📋

• Description: List cascading year, make, model, trim, or variant options for dropdowns (Vehicle Specifications)

• Parameters:

  • dimension (string, optional): years | makes | models | trims | variants
  • year, make, model, trim (all optional filters)

• Example Prompts:

  What years does CarsXE have vehicle data for?

  List Toyota models

  What Tacoma variants were available in 2026?

• Output: Markdown list of the inferred or requested dimension

19. get_ownership_by_vin 👤

• Description: Enterprise — look up registered owner(s) for a VIN

• Parameters:

  • vin (string, required): 17-character VIN
  • include (string, optional): demographics,emails,phones,vehicle_history

• Example Prompts:

  Who is the registered owner of VIN 1FT8X3BT0BEA61538?

• Output: Markdown with owners, contact info, demographics, and vehicle history. Billed per owner record.

20. get_ownership_by_person 👤

• Description: Enterprise — look up a person by name, street address, and ZIP

• Parameters:

  • firstName, lastName, address, zip (required)
  • include (string, optional)

• Example Prompts:

  Look up John Sample at 123 Example St, ZIP 90210

• Output: Markdown with matched people, contact info, and linked vehicles

21. get_ownership_by_address 👤

• Description: Enterprise — look up residents at a street address + ZIP

• Parameters:

  • address, zip (required)
  • include, variant (optional; prefer include)

• Example Prompts:

  Who lives at 123 Example St in ZIP 90210?

• Output: Markdown with residents and linked vehicles

22. get_ownership_by_zip 👤

• Description: Enterprise — search people in a 5-digit ZIP with optional filters

• Parameters:

  • zip (string, required)
  • gender, minAge, maxAge, income, page, limit, include, variant (optional)

• Example Prompts:

  Find people in ZIP 90210 aged 45+

  Search ZIP 49646 for women with income code F

• Output: Markdown page of matching records. Billed per record returned (default limit 15, max 100).

23. render_vehicle_card 🖼️

• Description: Render a visual VIN identity + key-specs card. Always call get_vehicle_specs first and pass its structuredContent. (Vehicle Specifications)

• Parameters: vin (required) plus optional year, make, model, trim, style, engine, transmission, drivetrain, fuel, MPG, seating, MSRP, built-in country

• Example Prompts:

  Get specs for VIN WBAFR7C57CC811956, then show the vehicle card.

• Output: MCP Apps / ChatGPT iframe card. Text fallback summarizes the vehicle.

24. render_market_value 🖼️

• Description: Render retail and trade-in value bands. Always call get_market_value first and pass its structuredContent. (Vehicle Market Value)

• Example Prompts:

  What's VIN WBAFR7C57CC811956 worth in California? Then show the market value card.

• Output: MCP Apps / ChatGPT iframe card. Text fallback summarizes the valuation.

25. render_recalls 🖼️

• Description: Render an open-recalls list. Always call get_vehicle_recalls first and pass its structuredContent. (Vehicle Recalls)

• Example Prompts:

  Check recalls for VIN 1C4JJXR64PW696340 and show the recalls card.

• Output: MCP Apps / ChatGPT iframe card. Text fallback reports recall count.

🔗 Chaining Tools — Power User Examples

The real power of CarsXE MCP comes from chaining tools in a single conversation:

Scenario 1 — Pre-purchase due diligence:

1. Decode plate 7XER187 in California

2. Now get its full history

3. Does it have any open recalls?

4. What's it worth if I buy it today?

Scenario 2 — Spotted a car on the street:

1. Read the plate from this image: [photo URL]

2. Look up that plate in Texas

3. Show me photos of that car model

Scenario 3 — Mechanic / service shop:

1. Decode this VIN from the dashboard photo: [image URL]

2. Get its full specs

3. My customer says the check engine code is P0300 — what does that mean for this vehicle?

Scenario 4 — Fleet recall scan without VINs:

1. List Toyota models for 2020

2. Check recalls for a 2020 Toyota Camry

3. Submit a recalls batch for these inventory VINs: [list]

4. Check the batch status, then show results

🔐 OAuth 2.1 (Claude.ai custom connector)

The hosted server at https://mcp.carsxe.com/mcp supports two authentication methods:

1. API key (unchanged) — X-API-Key header, Authorization: Bearer <api-key>, or ?key= query parameter. Used by Claude Desktop / mcp-remote and local clients.
2. OAuth 2.1 — used by hosted MCP clients such as the Claude.ai custom connector. Clicking Connect in Claude.ai runs a standard Authorization Code + PKCE flow: dynamic client registration (RFC 7591), browser sign-in on the CarsXE consent page, then token exchange. Access tokens (mcp_at_*, 1 h) map to the user's CarsXE API key; refresh tokens (mcp_rt_*, 90 d) are rotated on every refresh.

Requests with no credentials get 401 with a WWW-Authenticate challenge, which is what prompts Claude.ai to start the flow.

Environment variables

The Cloudflare Workers deployment (src/index.ts) does not serve the OAuth surface — only the GCP Cloud Run deployment (src/index.gcp.ts) behind mcp.carsxe.com does.