Servidor MCP de Bouncie

Un servidor de Model Context Protocol (MCP) para la API de seguimiento de vehículos OBD2 de Bouncie. Proporciona a Claude, ChatGPT o cualquier asistente de IA compatible con MCP acceso en tiempo real a los datos de tu vehículo: ubicación, viajes, diagnósticos, nivel de combustible y más.

Qué hace

Conecta tu rastreador GPS Bouncie a la IA. Haz preguntas en lenguaje natural como:

• "¿Dónde está mi coche ahora mismo?"

• "Muéstrame mis viajes de la semana pasada"

• "¿Está encendida la luz de revisión del motor? ¿Qué códigos tiene?"

• "¿Cuánto combustible me queda?"

• "¿Cuál fue mi viaje más largo esta semana?"

Related MCP server: Unoffical Polestar 2 MCP

Características

• Seguimiento de vehículos en tiempo real — Ubicación GPS, velocidad, rumbo, dirección

• Historial y análisis de viajes — distancia, duración, velocidad media/máxima, combustible consumido, recuento de frenazos y aceleraciones bruscas, trazas GPS (polilínea o GeoJSON)

• Diagnóstico del vehículo — estado de la luz de revisión del motor (MIL), códigos de diagnóstico de problemas (DTC) OBD2, salud de la batería

• Información del vehículo — marca, modelo, año, VIN, motor, odómetro, nivel de combustible

• OAuth multiusuario — el modo HTTP actúa como proxy del OAuth de Claude.ai hacia el de Bouncie, por lo que cada usuario se autoriza con su propia cuenta de Bouncie

• Modos Stdio + HTTP — ejecútalo localmente con un token de acceso preemitido, o alójalo de forma centralizada para múltiples usuarios

• Listo para Docker — despliégalo en cualquier lugar con HTTPS

Inicio rápido

Modo local (stdio)

npm install && npm run build

Añádelo a la configuración MCP de Claude Desktop o Claude Code:

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

El modo Stdio utiliza un token de acceso de Bouncie obtenido previamente, sin flujo de OAuth. Utiliza el modo HTTP para despliegues multiusuario.

Modo remoto (HTTP) con Docker

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

El servidor expone:

• /mcp — punto final MCP (autenticación con token Bearer)

• /authorize — inicia el flujo de OAuth, redirige al usuario a Bouncie

• /callback — destino de redirección OAuth de Bouncie

• /token — punto final de intercambio de tokens para clientes MCP

• /register — registro dinámico de clientes RFC 7591

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

• /health — comprobación de estado

Configuración de la aplicación Bouncie

1. Regístrate en bouncie.dev y crea una aplicación

2. Anota tu Client ID y Client Secret

3. Establece la Redirect URL en {PUBLIC_URL}/callback (ej. https://bouncie.example.com/callback)

Eso es todo el trabajo en el portal; los usuarios se autorizan individualmente a través del flujo de OAuth cuando se conectan mediante Claude.ai.

Variables de entorno

Modo Stdio (usuario único)

Modo HTTP (multiusuario)

Herramientas

get_vehicles

Lista todos los vehículos de la cuenta con estadísticas en vivo.

Devuelve: información del vehículo (marca/modelo/año, VIN, IMEI, apodo) y estadísticas en vivo (ubicación GPS, velocidad, nivel de combustible, odómetro, estado del motor, batería, luz de revisión del motor, DTCs).

get_vehicle

Obtén un solo vehículo por VIN o IMEI. Se requiere al menos un identificador.

get_trips

Obtén el historial de viajes de un vehículo.

Ventana de fecha máxima de 1 semana. Por defecto, los últimos 7 días.

Devuelve: distancia, duración, velocidad media/máxima, combustible consumido, recuento de frenazos/aceleraciones bruscas, odómetro, traza GPS.

get_user

Obtén el perfil del usuario autenticado.

Marcas de tiempo

Todas las marcas de tiempo de la API de Bouncie están en UTC. Cada vehículo/viaje incluye un campo de desplazamiento de zona horaria (localTimeZone o timeZone, ej. "-0500") para la conversión a hora local.

Desarrollo

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

Arquitectura

• src/index.ts — punto de entrada de transporte stdio

• src/http.ts — punto de entrada HTTP/Express con OAuth

• src/server.ts — definiciones de herramientas MCP

• src/api.ts — cliente de la API REST de Bouncie

• src/oauth.ts — proveedor de OAuth que actúa como proxy del OAuth de Claude.ai hacia el de Bouncie (compatible con PKCE)

• src/types.ts — tipos de TypeScript para vehículos, viajes y eventos de webhook

Eventos de Webhook de Bouncie

La API de Bouncie también admite webhooks (documentados aquí como referencia):

Licencia

MIT