Bouncie MCP 서버

Bouncie OBD2 차량 추적 API를 위한 Model Context Protocol (MCP) 서버입니다. Claude, ChatGPT 또는 MCP 호환 AI 어시스턴트에게 위치, 주행 기록, 진단 정보, 연료 잔량 등 차량 데이터에 대한 실시간 액세스 권한을 부여하세요.

주요 기능

Bouncie GPS 추적기를 AI에 연결하세요. 다음과 같은 자연어 질문을 할 수 있습니다:

• "내 차가 지금 어디에 있지?"

• "지난주 주행 기록을 보여줘"

• "엔진 경고등이 켜져 있나? 어떤 코드지?"

• "연료가 얼마나 남았지?"

• "이번 주에 가장 길게 주행한 기록은 뭐야?"

Related MCP server: Unoffical Polestar 2 MCP

기능

• 실시간 차량 추적 — GPS 위치, 속도, 방향, 주소

• 주행 기록 및 분석 — 거리, 시간, 평균/최고 속도, 연료 소모량, 급제동 및 급가속 횟수, GPS 경로(폴리라인 또는 GeoJSON)

• 차량 진단 — 엔진 경고등(MIL) 상태, OBD2 진단 문제 코드(DTC), 배터리 상태

• 차량 정보 — 제조사, 모델, 연식, VIN, 엔진, 주행 거리계, 연료 잔량

• 다중 사용자 OAuth — HTTP 모드는 Claude.ai의 OAuth를 Bouncie의 OAuth로 프록시하여, 각 사용자가 자신의 Bouncie 계정으로 인증하도록 합니다.

• Stdio + HTTP 모드 — 미리 발급된 액세스 토큰으로 로컬에서 실행하거나, 여러 사용자를 위해 중앙에서 호스팅할 수 있습니다.

• Docker 지원 — HTTPS를 사용하여 어디에나 배포 가능

빠른 시작

로컬 (stdio) 모드

npm install && npm run build

Claude Desktop 또는 Claude Code MCP 설정에 추가하세요:

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

Stdio 모드는 미리 획득한 Bouncie 액세스 토큰을 사용하며, OAuth 흐름이 필요 없습니다. 다중 사용자 배포에는 HTTP 모드를 사용하세요.

원격 (HTTP) 모드 (Docker 사용)

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

서버는 다음 엔드포인트를 제공합니다:

• /mcp — MCP 엔드포인트 (Bearer 토큰 인증)

• /authorize — OAuth 흐름을 시작하고 사용자를 Bouncie로 리디렉션

• /callback — Bouncie의 OAuth 리디렉션 대상

• /token — MCP 클라이언트를 위한 토큰 교환 엔드포인트

• /register — RFC 7591 동적 클라이언트 등록

• /.well-known/oauth-authorization-server — RFC 8414 메타데이터

• /health — 상태 확인

Bouncie 앱 설정

1. bouncie.dev에 등록하고 앱을 생성합니다.

2. Client ID와 Client Secret을 기록해 둡니다.

3. Redirect URL을 {PUBLIC_URL}/callback으로 설정합니다 (예: https://bouncie.example.com/callback).

포털 작업은 이것으로 끝입니다. 사용자가 Claude.ai를 통해 연결할 때 OAuth 흐름을 통해 개별적으로 인증하게 됩니다.

환경 변수

Stdio 모드 (단일 사용자)

HTTP 모드 (다중 사용자)

도구

get_vehicles

계정의 모든 차량과 실시간 상태를 나열합니다.

반환값: 차량 정보(제조사/모델/연식, VIN, IMEI, 별칭) 및 실시간 상태(GPS 위치, 속도, 연료 잔량, 주행 거리계, 엔진 작동 상태, 배터리, 엔진 경고등, DTC).

get_vehicle

VIN 또는 IMEI로 단일 차량 정보를 가져옵니다. 최소 하나의 식별자가 필요합니다.

get_trips

차량의 주행 기록을 가져옵니다.

날짜 범위는 최대 1주일입니다. 기본값은 최근 7일입니다.

반환값: 거리, 시간, 평균/최고 속도, 연료 소모량, 급제동/급가속 횟수, 주행 거리계, GPS 경로.

get_user

인증된 사용자의 프로필을 가져옵니다.

타임스탬프

Bouncie API의 모든 타임스탬프는 UTC 기준입니다. 각 차량/주행 기록에는 현지 시간 변환을 위한 시간대 오프셋 필드(localTimeZone 또는 timeZone, 예: "-0500")가 포함되어 있습니다.

개발

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

아키텍처

• src/index.ts — stdio 전송 진입점

• src/http.ts — OAuth가 포함된 HTTP/Express 진입점

• src/server.ts — MCP 도구 정의

• src/api.ts — Bouncie REST API 클라이언트

• src/oauth.ts — Claude.ai의 OAuth를 Bouncie로 프록시하는 OAuth 제공자 (PKCE 지원)

• src/types.ts — 차량, 주행 기록 및 웹훅 이벤트를 위한 TypeScript 타입

Bouncie 웹훅 이벤트

Bouncie API는 웹훅도 지원합니다 (참고용):

라이선스

MIT