# Smartcar MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes Smartcar's vehicle API as tools for AI agents. Enables Claude, ChatGPT, and other MCP-compatible clients to query vehicle telemetry and send commands using natural language.

## Overview

This server wraps Smartcar's M2M (machine-to-machine) API using OAuth2 client credentials. It handles token acquisition and caching automatically, so AI agents interact with vehicles without managing auth.

**16 tools across 4 categories:**

| Category | Tools |
|---|---|
| Connections | `list_connections`, `get_connection`, `delete_connection`, `delete_user` |
| Signals (telemetry) | `get_signals`, `get_signal` |
| Vehicle commands | `lock_vehicle`, `unlock_vehicle`, `start_charge`, `stop_charge`, `set_charge_limit`, `set_navigation_destination` |
| Management | `list_applications`, `get_application`, `list_application_secrets` |

## Usage

No installation needed. Add this to your `claude_desktop_config.json` (or equivalent MCP client config):

```json
{
  "mcpServers": {
    "smartcar": {
      "command": "npx",
      "args": ["-y", "smartcar-mcp"],
      "env": {
        "SMARTCAR_CLIENT_ID": "your-client-id",
        "SMARTCAR_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `SMARTCAR_CLIENT_ID` | Yes | — | Your Smartcar M2M client ID |
| `SMARTCAR_CLIENT_SECRET` | Yes | — | Your Smartcar M2M client secret |
| `SMARTCAR_API_URL` | No | `https://vehicle.api.smartcar.com/v3` | Vehicle API base URL |
| `SMARTCAR_AUTH_URL` | No | `https://iam.smartcar.com` | Auth token endpoint |
| `SMARTCAR_MANAGEMENT_API_URL` | No | `https://management.api.smartcar.com/v3` | Management API base URL |

## Development

```bash
git clone https://github.com/thachdoSC/smartcar-mcp-test
cd smartcar-mcp
npm install
npm run dev   # run from source
npm run build # compile to dist/
```

## Tools Reference

### Connections

**`list_connections`** — List vehicle connections with optional filters.

| Parameter | Type | Description |
|---|---|---|
| `userId` | string? | Filter by user ID |
| `vehicleId` | string? | Filter by vehicle ID |
| `vehicleMode` | `live` \| `simulated`? | Filter by vehicle mode |
| `pageNumber` | number? | Page number |
| `pageSize` | number? | Results per page |

**`get_connection`** — Get a single connection by ID.

**`delete_connection`** — Delete a connection by ID.

**`delete_user`** — Delete a user and all associated data.

---

### Signals (Telemetry)

**`get_signals`** — List all available signals for a vehicle.

| Parameter | Type | Description |
|---|---|---|
| `vehicle_id` | string | Vehicle ID |
| `user_id` | string | User ID |
| `pageNumber` | number? | Page number |
| `pageSize` | number? | Results per page |

**`get_signal`** — Fetch the current value of a specific signal.

| Parameter | Type | Description |
| --- | --- | --- |
| `vehicle_id` | string | Vehicle ID |
| `user_id` | string | User ID |
| `signal_code` | string | Signal code (see below) |

<details>
<summary>Available signal codes (122 total)</summary>

**Charge:** `charge.ischarging`, `charge.voltage`, `charge.wattage`, `charge.amperage`, `charge.limit`, `charge.estimation.durationtocompletion`, `charge.estimation.distance_added`, `charge.estimation.kwh_added`, `charge.estimation.percent_added`, `charge.session.id`, `charge.session.starttime`, `charge.session.endtime`, `charge.session.kwhadded`, `charge.session.milesadded`, `charge.session.porttype`, `charge.session.cost`, `charge.schedule.type`, `charge.schedule.starttime`, `charge.schedule.day`, `charge.schedule.enabled`, `charge.porttype`, `charge.portstatus`

**Climate:** `climate.externaltemperature`, `climate.internaltemperature`

**Closure:** `closure.door`, `closure.lock`, `closure.window`, `closure.sunroof`, `closure.fronttrunk`, `closure.reartrunk`, `closure.chargeport`

**Connectivity:** `connectivity.firmware`, `connectivity.isonline`, `connectivity.sleepstate`, `connectivity.lastseenat`

**Diagnostics:** `diagnostics.faultcodes`, `diagnostics.oil`, `diagnostics.emissions`, `diagnostics.abs`, `diagnostics.airbag`, `diagnostics.battery.maintenancestatus`, `diagnostics.battery.range`, `diagnostics.battery.soc`, `diagnostics.brakebooster`, `diagnostics.brakefluid`, `diagnostics.collision`, `diagnostics.coolant`, `diagnostics.cruisecontrol`, `diagnostics.enginelight`, `diagnostics.hazardlights`, `diagnostics.headlights`, `diagnostics.park`, `diagnostics.stabilitycontrol`, `diagnostics.steeringlock`, `diagnostics.transmission`, `diagnostics.washerfluid`

**HVAC:** `hvac.cabintemperature`, `hvac.defroster`, `hvac.heater`, `hvac.temperatureset`, `hvac.ventilation`

**ICE (Internal Combustion Engine):** `ice.fuel.level`, `ice.fuel.range`, `ice.fuel.percentremaining`, `ice.oillife`

**Location:** `location.precise`, `location.ishome`

**Low voltage battery:** `lowvoltagebattery.stateofcharge`, `lowvoltagebattery.status`

**Motion:** `motion.speed`

**Odometer:** `odometer.distance`

**Service:** `service.isinservice`, `service.records`

**Surveillance:** `surveillance.brand`, `surveillance.isenabled`

**Traction battery:** `tractionbattery.stateofcharge`, `tractionbattery.range`, `tractionbattery.heating`, `tractionbattery.capacity.kwh`, `tractionbattery.capacity.usableKwh`, `tractionbattery.limit`, `tractionbattery.temperature`, `tractionbattery.chargecompletiontime`, `tractionbattery.fullchargetime`

**Transmission:** `transmission.drivemode`, `transmission.gear`

**Vehicle ID:** `vehicleid.vin`, `vehicleid.color`, `vehicleid.trim`, `vehicleid.packages`, `vehicleid.nickname`

**Vehicle user account:** `vehicleuseraccount.grantedpermissions`, `vehicleuseraccount.role`

**Wheel:** `wheel.style`, `wheel.tires`

</details>

---

### Vehicle Commands

All command tools require `vehicle_id` and `user_id`.

**`lock_vehicle`** — Lock vehicle doors.

**`unlock_vehicle`** — Unlock vehicle doors.

**`start_charge`** — Start EV charging.

**`stop_charge`** — Stop EV charging.

**`set_charge_limit`** — Set the maximum charge level.

| Parameter | Type | Description |
|---|---|---|
| `percent` | number | Target charge % (50–100) |

**`set_navigation_destination`** — Send a GPS destination to the vehicle's nav system.

| Parameter | Type | Description |
|---|---|---|
| `latitude` | number | Latitude (-90 to 90) |
| `longitude` | number | Longitude (-180 to 180) |

---

### Management

**`list_applications`** — List all Smartcar applications in your organization.

**`get_application`** — Get details for a specific application by ID.

**`list_application_secrets`** — List credentials for an application (secret values are not returned).

## Project Structure

```
src/
├── index.ts          # Server entry point — wires up tools and transport
├── auth.ts           # OAuth2 token manager with in-memory caching
├── client.ts         # HTTP client for Smartcar REST APIs
└── tools/
    ├── connections.ts # Connection and user management tools
    ├── signals.ts     # Vehicle telemetry tools
    ├── commands.ts    # Vehicle control command tools
    └── management.ts  # Application management tools
```

## Authentication

The server uses OAuth2 client credentials (M2M flow). Tokens are cached in memory and refreshed automatically 60 seconds before expiry. No manual token management is needed.