Content
# Vehicle Imagery MCP Server
[](https://www.npmjs.com/package/vehicleimagery-mcp)
[](./LICENSE)
A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Vehicle Imagery API](https://api.vehicleimagery.com). 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](https://www.npmjs.com/package/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
[](https://cursor.com/en/install-mcp?name=vehicleimagery&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInZlaGljbGVpbWFnZXJ5LW1jcCJdLCJlbnYiOnsiVklfQVBJX0tFWSI6IllPVVJfQVBJX0tFWSJ9fQ%3D%3D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=vehicleimagery&inputs=%5B%7B%22id%22%3A%22vi_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Vehicle+Imagery+API+key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22vehicleimagery-mcp%22%5D%2C%22env%22%3A%7B%22VI_API_KEY%22%3A%22%24%7Binput%3Avi_api_key%7D%22%7D%7D)
[](#claude-code)
[](#claude-desktop)
[](#openai-codex)
[](#google-antigravity)
[](#windsurf)
[](#gemini-cli)
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`:
```json
{
"mcpServers": {
"vehicleimagery": {
"command": "npx",
"args": ["-y", "vehicleimagery-mcp"],
"env": {
"VI_API_KEY": "your_api_key"
}
}
}
}
```
### Claude Code
```bash
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):
```json
{
"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:
```json
{
"servers": {
"vehicleimagery": {
"command": "npx",
"args": ["-y", "vehicleimagery-mcp"],
"env": {
"VI_API_KEY": "your_api_key"
}
}
}
}
```
### OpenAI Codex
```bash
codex mcp add vehicleimagery --env VI_API_KEY=your_api_key -- npx -y vehicleimagery-mcp
```
Or add this to `~/.codex/config.toml`:
```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:
```json
{
"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
```bash
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:
```bash
VI_API_KEY=your_key node dist/cli.js
```
You can also use the server programmatically:
```ts
import { createServer } from "vehicleimagery-mcp";
import { VehicleImagery } from "vehicleimagery";
const server = createServer(new VehicleImagery({ apiKey: "your_key" }));
```
## Related
- [vehicleimagery](https://github.com/vehicleimagery/vehicleimagery-sdk): the TypeScript and JavaScript SDK this server is built on
- [API documentation](https://website-dta.pages.dev/documentation/)
- [OpenAPI spec](https://api.vehicleimagery.com/api/openapi.json)
## License
[MIT](./LICENSE), Vehicle Imagery.
