Bouncie MCP Server

A Model Context Protocol (MCP) server for the Bouncie OBD2 vehicle tracking API. Give Claude, ChatGPT, or any MCP-compatible AI assistant real-time access to your vehicle data — location, trips, diagnostics, fuel level, and more.

What it does

Connect your Bouncie GPS tracker to AI. Ask natural language questions like:

• "Where is my car right now?"

• "Show me my trips from last week"

• "Is my check engine light on? What codes?"

• "How much fuel do I have left?"

• "What was my longest drive this week?"

Features

• Real-time vehicle tracking — GPS location, speed, heading, address

• Trip history & analytics — distance, duration, average/max speed, fuel consumed, hard braking & acceleration counts, GPS traces (polyline or GeoJSON)

• Vehicle diagnostics — check engine light (MIL) status, OBD2 diagnostic trouble codes (DTCs), battery health

• Vehicle info — make, model, year, VIN, engine, odometer, fuel level

• Multi-user OAuth — HTTP mode proxies Claude.ai's OAuth to Bouncie's, so each user authorizes with their own Bouncie account

• Stdio + HTTP modes — run locally with a pre-issued access token, or host centrally for multiple users

• Docker-ready — deploy anywhere with HTTPS

Quick Start

Local (stdio) mode

npm install && npm run build

Add to Claude Desktop or Claude Code MCP settings:

{
  "mcpServers": {
    "bouncie": {
      "command": "node",
      "args": ["/path/to/bouncie-mcp/dist/index.js"],
      "env": {
        "BOUNCIE_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

Stdio mode uses a pre-obtained Bouncie access token — no OAuth flow. Use HTTP mode for multi-user deployments.

Remote (HTTP) mode with Docker

cp .env.example .env  # fill in your credentials
docker compose up -d

The server exposes:

• /mcp — MCP endpoint (Bearer token auth)

• /authorize — kicks off the OAuth flow, redirects the user to Bouncie

• /callback — Bouncie's OAuth redirect target

• /token — token exchange endpoint for MCP clients

• /register — RFC 7591 dynamic client registration

• /.well-known/oauth-authorization-server — RFC 8414 metadata

• /health — health check

Bouncie App Setup

1. Register at bouncie.dev and create an app

2. Note your Client ID and Client Secret

3. Set the Redirect URL to {PUBLIC_URL}/callback (e.g. https://bouncie.example.com/callback)

That's all the portal work — users authorize individually through the OAuth flow when they connect via Claude.ai.

Environment Variables

Stdio mode (single-user)

HTTP mode (multi-user)

Tools

get_vehicles

List all vehicles on the account with live stats.

Returns: vehicle info (make/model/year, VIN, IMEI, nickname) and live stats (GPS location, speed, fuel level, odometer, engine running status, battery, check engine light, DTCs).

get_vehicle

Get a single vehicle by VIN or IMEI. At least one identifier required.

get_trips

Get trip history for a vehicle.

Date window max 1 week. Defaults to last 7 days.

Returns: distance, duration, average/max speed, fuel consumed, hard braking/acceleration counts, odometer, GPS trace.

get_user

Get the authenticated user's profile.

Timestamps

All timestamps from the Bouncie API are in UTC. Each vehicle/trip includes a timezone offset field (localTimeZone or timeZone, e.g. "-0500") for local time conversion.

Development

npm run dev        # Run with tsx (hot reload)
npm run build      # Compile TypeScript
npm test           # Run tests (21 tests)
npm run lint       # Type check

Architecture

• src/index.ts — stdio transport entry point

• src/http.ts — HTTP/Express entry point with OAuth

• src/server.ts — MCP tool definitions

• src/api.ts — Bouncie REST API client

• src/oauth.ts — OAuth provider that proxies Claude.ai's OAuth to Bouncie's (PKCE supported)

• src/types.ts — TypeScript types for vehicles, trips, and webhook events

Bouncie Webhook Events

The Bouncie API also supports webhooks (documented here for reference):

License

MIT