Vehicle Imagery MCP Server

A Model Context Protocol server for the Vehicle Imagery API. It lets AI assistants such as Claude browse the vehicle catalog and resolve studio quality car images as signed CDN URLs, with paint colors, camera views, shadows, transparent backgrounds and more.

Built on the official vehicleimagery SDK.

What it enables

Ask your assistant things like:

• Show me a 2023 BMW X5 from the front in Alpine White
• Which colors are available for the Tesla Model 3
• Get me a transparent rear view of an Audi Q5 as WebP, 1200 px wide

The assistant walks the catalog, resolves a signed image URL and can embed it directly.

Requirements

• Node.js 18 or newer
• A Vehicle Imagery API key

Install

The Cursor and VS Code buttons install directly. The other tools have no install link standard, so their buttons jump to the matching setup section below. Replace YOUR_API_KEY with your key after installing.

Setup

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "vehicleimagery": {
      "command": "npx",
      "args": ["-y", "vehicleimagery-mcp"],
      "env": {
        "VI_API_KEY": "your_api_key"
      }
    }
  }
}

Claude Code

claude mcp add vehicleimagery --env VI_API_KEY=your_api_key -- npx -y vehicleimagery-mcp

Cursor

Use the install button above, or add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "vehicleimagery": {
      "command": "npx",
      "args": ["-y", "vehicleimagery-mcp"],
      "env": {
        "VI_API_KEY": "your_api_key"
      }
    }
  }
}

VS Code

Use the install button above, or add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "vehicleimagery": {
      "command": "npx",
      "args": ["-y", "vehicleimagery-mcp"],
      "env": {
        "VI_API_KEY": "your_api_key"
      }
    }
  }
}

OpenAI Codex

codex mcp add vehicleimagery --env VI_API_KEY=your_api_key -- npx -y vehicleimagery-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.vehicleimagery]
command = "npx"
args = ["-y", "vehicleimagery-mcp"]
env = { "VI_API_KEY" = "your_api_key" }

Google Antigravity

Open the MCP server settings in the agent panel, choose to edit the raw config and add:

{
  "mcpServers": {
    "vehicleimagery": {
      "command": "npx",
      "args": ["-y", "vehicleimagery-mcp"],
      "env": {
        "VI_API_KEY": "your_api_key"
      }
    }
  }
}

Windsurf

Add the same mcpServers block as above to ~/.codeium/windsurf/mcp_config.json.

Gemini CLI

Add the same mcpServers block as above to ~/.gemini/settings.json.

Any other MCP client

The server speaks the standard stdio transport. Launch command: npx -y vehicleimagery-mcp with the VI_API_KEY environment variable set. Alternatively pass the key as an argument: npx -y vehicleimagery-mcp --api-key your_api_key.

Tools

Tool	Purpose
search_vehicles	Fuzzy search brands and models by free text
list_brands	List every available brand
list_models	List the models of a brand
list_years	List the model years of a brand and model
list_variants	List the variants of a brand, model and year
list_trims	List the trims of a configuration
get_vehicle_config	Views, paint colors and features of one configuration in one call
get_vehicle_image	Resolve a signed image URL with transform options
list_reference_views	All camera view names known to the service
list_reference_colors	All paint color names known to the service
get_account_info	What the configured API key is allowed to do

The catalog is a hierarchy: brand, model, year, variant, trim, view. The tool descriptions guide the assistant through it automatically.

Image options

get_vehicle_image supports: format (png, webp, jpeg, avif, auto), resolution presets, ratio padding, explicit width, height and quality, paint color by name, shadow, transparency, ground and mirroring. The returned image_url is a signed CDN URL that stays valid for about 7 days and can be embedded directly.

Environment variables

Variable	Purpose
VI_API_KEY	Your Vehicle Imagery API key (required)
VI_BASE_URL	Override the API base URL (optional)

Development

git clone https://github.com/vehicleimagery/vehicleimagery-mcp.git
cd vehicleimagery-mcp
npm install
npm run typecheck
npm test
npm run build

Run the built server locally:

VI_API_KEY=your_key node dist/cli.js

You can also use the server programmatically:

import { createServer } from "vehicleimagery-mcp";
import { VehicleImagery } from "vehicleimagery";

const server = createServer(new VehicleImagery({ apiKey: "your_key" }));

Related

• vehicleimagery: the TypeScript and JavaScript SDK this server is built on
• API documentation
• OpenAPI spec

License

MIT, Vehicle Imagery.