teslafi-mcp: Instructions file for Claude Code

TeslaFi MCP — Claude Code cold-start guide

This file orients a fresh Claude Code session (and the human running it) on this repository. Claude Code loads it automatically; you can also read it top-to-bottom as a maintainer's onboarding brief. If you are evaluating or adopting this project (e.g. TeslaFi), start here — it is MIT-licensed and yours to run, fork, rebrand, or ship without restriction.

A good first prompt for a new session:

"Read CLAUDE.md, then give me a 5-line summary of the architecture and run the test suite so I know the tree is healthy."

---

What this is

A Model Context Protocol server that exposes the TeslaFi API to MCP clients (Claude Desktop, etc.), so a user can ask an assistant about their vehicle in natural language. It is packaged both as a plain Node server and as an MCPB extension bundle (.mcpb) for one-click install into Claude Desktop.

Seven tools: tesla_get_current_data, tesla_get_drives, tesla_get_charges, tesla_get_trips_for_month, tesla_analyze_home_work_trips, tesla_get_locations, and tesla_send_command (vehicle control — disabled by default).

Quick start

Requirements: Node 20+ (18+ runs the built server, but the test toolchain needs 20+), and a TeslaFi API token from https://teslafi.com/api.php.

git clone https://github.com/Zenotech-bv/teslafi-mcp.git
cd teslafi-mcp
npm install
npm run build      # tsc -> dist/
npm test           # vitest run — all HTTP is mocked, nothing hits the network

Run the server standalone:

TESLA_API_TOKEN=your_token node dist/index.js     # speaks MCP over stdio

Rebuild the extension bundle:

npx @anthropic-ai/mcpb pack   # -> teslafi-mcp.mcpb (gitignored)

Architecture map

Path	Role
src/services/tesla-api.ts	The TeslaFi client and all business logic: HTTP with retry/backoff, rate-limit pacing, in-memory history cache, the command allowlist, quota tracking, the units system, and the UpdateChecker. Also the exported VERSION constant. Most changes land here.
src/index.ts	MCP server wiring: registers the 7 tools, parses args through the Zod schemas, renders markdown vs JSON output, and surfaces quota/update notices.
src/schemas.ts	Zod input schemas for every tool. All .strict() — unknown keys are rejected.
tests/tesla-api.test.ts, tests/server-tools.test.ts	vitest suite (~360 tests). Every test mocks axios; none contact the real API.
manifest.json	MCPB extension manifest: metadata, tool list, and user_config (token + toggles).
package.json, tsconfig.json, .mcpbignore	Build config and bundle-exclusion rules.
README.md, SECURITY.md, CONTRIBUTING.md, CHANGELOG.md	User- and contributor-facing docs.