weconnect_mvp

MCP Server for Volkswagen Vehicles
A developer-focused server that exposes information from VW vehicles via a Model Context Protocol (MCP) interface. This project is designed for integration, automation, and experimentation with connected car data.

---

See It In Action

Control your VW vehicle through AI assistants like Claude Desktop and GitHub Copilot

---

Quick Start

Get up and running in 3 steps:

1. Install

   git clone https://github.com/Smengerl/weconnect_mvp.git
   cd weconnect_mvp
   ./scripts/setup.sh

2. Configure
   Edit src/config.json with your VW credentials (username, password, spin)

3. Use with AI Assistant

   Option A: Claude Desktop

   ./scripts/create_claude_config.sh  # Copy output to Claude config

   Restart Claude Desktop and ask: "What vehicles are available?"

   Option B: GitHub Copilot (VS Code)

   ./scripts/create_github_copilot_config.sh  # Follow instructions to add to VS Code mcp.json

   Restart VS Code and ask in Copilot Chat: "What vehicles are available?"

   Option C: Cloud deployment (ChatGPT, Claude.ai, …)
   Deploy to Railway (or any Docker host) – see Cloud Deployment below.

For detailed instructions, see sections below.

---

Features

• MCP Server: Provides a standard MCP interface for accessing vehicle data
• Volkswagen Integration: Connects to VW vehicles using the carconnectivity library
• AI Assistant Ready: Works with Claude Desktop, VS Code Copilot, ChatGPT, Claude.ai and other MCP-compatible tools
• Cloud Deployable: Ships with Dockerfile, docker-compose.yml and Railway config for one-command cloud deployment
• API-Key Authentication: Bearer token auth for secure public HTTP endpoints
• Flexible CLI: Multiple transport modes (stdio for local, HTTP for cloud)
• Configurable: Credentials via config file or environment variables (for Docker / Railway)

Getting Started

Prerequisites

• Python 3.8+
• VW account credentials (username, password, and optionally a spin)
• (Recommended) Virtual environment

Installation

Quick Start (Recommended):

Simply run the setup script which handles everything automatically:

git clone https://github.com/Smengerl/weconnect_mvp.git
cd weconnect_mvp
./scripts/setup.sh

The script will:

• ✅ Detect your Python installation
• ✅ Create a virtual environment at .venv/
• ✅ Install all dependencies
• ✅ Create configuration template

Manual Installation (Alternative):

git clone https://github.com/Smengerl/weconnect_mvp.git
cd weconnect_mvp
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Windows-Specific Notes

⚠️ Important for Windows Users:

The setup script automatically detects and avoids Microsoft Store Python (which doesn't work). If you see errors about Python not found:

1. Install Python from python.org (not Microsoft Store)

   • Download from python.org
   • ✅ Check "Add Python to PATH" during installation

2. Disable Microsoft Store Python alias (if you have it):

   • Settings → Apps → Advanced app settings → App execution aliases
   • Turn OFF: python.exe, python3.exe, python3.x.exe

3. Verify your Python installation:

   # Should return a path like: C:\Program Files\PythonXXX\python.exe
   where python

4. Run diagnostic tool:

   & .\scripts\diagnose_python.ps1

Configuration

The server requires a configuration file (default: src/config.json).
You must create this file based on the provided example and add your VW credentials.

Step 1: Copy the example configuration

cp src/config.example.json src/config.json

Step 2: Edit the configuration with your VW credentials

# Use your preferred editor
nano src/config.json
# or
code src/config.json

Configuration Parameters:

• username: Your VW WeConnect account email
• password: Your VW WeConnect account password
• spin: Your VW S-PIN (4 digits, required for some vehicle commands)
• interval: Data refresh interval in seconds (default: 300 = 5 minutes)
• max_age: Maximum age of cached data in seconds

Security Notice:
⚠️ NEVER commit src/config.json to version control!
This file is automatically excluded via .gitignore to protect your credentials.

---

Usage

The server supports two transport modes depending on the AI agent you want to use:

• stdio: When running MCP server locally on the same machine as your AI agent (Claude Desktop, VS Code Copilot)
• http: For cloud deployment or when the local AI agent requires this mode (e.g. ChatGPT)

CLI Options

You can start the MCP server using the provided CLI scripts or directly via Python:

1. Starting the server in foreground (with logs to console)

./scripts/start_server_fg.sh

2. Starting the server in background (with logs to file)

./scripts/start_server_bg.sh

If started in the background, stop the server using the script:

./scripts/stop_server.sh

Alternatively, kill the process via PID.

3. Starting the server directly via Python

python -m weconnect_mcp.cli.mcp_server_cli path/to/config.json --port 8765

CLI Parameters

The MCP server can be started with several command-line parameters to control its behavior:

Parameter	Default	Description
config	(required)	Path to the configuration file
--tokenstorefile	/tmp/tokenstore	Path for the token store file
--log-level	INFO	Set logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
--log-file	(stderr only)	Path to log file (if not set, logs to stderr only)
--transport	stdio	Transport mode: stdio (for AI) or http (for API)
--port	8667	Port for HTTP mode

Example:

python -m weconnect_mcp.cli.mcp_server_cli src/config.json --log-level DEBUG --log-file server.log --transport http --port 8765

---

AI Integration

This MCP server provides 18 tools (8 read + 10 command) that AI assistants can use to interact with your VW vehicle, plus 15 URI-based MCP Resources for declarative data access.

Source of truth: The canonical, up-to-date tool reference lives in
src/weconnect_mcp/server/AI_INSTRUCTIONS.md
and in the tool registration files
src/weconnect_mcp/server/mixins/read_tools.py / command_tools.py.

MCP Tools (Preferred for AI Assistants)

Read tools (8) — query vehicle data:

Tool	Description
get_vehicles	List all available vehicles (name, VIN, model)
get_vehicle_info	Basic vehicle info (model, year, type)
get_vehicle_state	Complete state snapshot (battery, doors, climate, position, …)
get_vehicle_doors	Door lock and open/closed status
get_battery_status	Quick battery level check (BEV/PHEV)
get_climatization_status	Climate control status and target temperature
get_charging_status	Charging details and remaining time (BEV/PHEV)
get_vehicle_position	GPS location (latitude, longitude, heading)

Command tools (10) — control vehicle remotely:

Tool	Description
lock_vehicle	Lock all doors
unlock_vehicle	Unlock all doors
start_climatization	Start climate control (optional target temperature in °C)
stop_climatization	Stop climate control
start_charging	Start charging session (BEV/PHEV)
stop_charging	Stop charging session (BEV/PHEV)
flash_lights	Flash lights for vehicle location (optional duration in seconds)
honk_and_flash	Honk and flash lights (optional duration in seconds)
start_window_heating	Start window/rear-window defrost
stop_window_heating	Stop window/rear-window defrost

MCP Resources (URI-Based Read Access)

Resources provide the same data as read tools via stable URIs and are suited for declarative access patterns. AI assistants should prefer Tools for interactive conversations.

Resource URI	Description
data://vehicles	List all vehicles
data://vehicle/{id}/info	Basic vehicle information
data://vehicle/{id}/state	Complete vehicle state snapshot
data://vehicle/{id}/doors	Door lock/open status
data://vehicle/{id}/windows	Window open/closed status
data://vehicle/{id}/tyres	Tyre pressure and temperature
data://vehicle/{id}/type	Propulsion type (BEV / PHEV / ICE)
data://vehicle/{id}/charging	Detailed charging status (BEV/PHEV)
data://vehicle/{id}/climate	Climate control status
data://vehicle/{id}/maintenance	Service schedule information
data://vehicle/{id}/range	Range and fuel/battery levels
data://vehicle/{id}/window-heating	Window heating/defrost status
data://vehicle/{id}/lights	Lights status
data://vehicle/{id}/position	GPS location
data://vehicle/{id}/battery	Quick battery check (BEV/PHEV)

What AI Assistants Can Do

✅ List vehicles and identify them by name or VIN
✅ Read full or targeted vehicle status (battery, doors, climate, position, …)
✅ Execute remote commands (lock, charge, climatize, flash lights, …)
✅ Answer natural questions like "Where is my car?" or "Is it locked?"
✅ Combine multiple queries and commands for complex tasks

---

Claude Desktop Integration

Generate your configuration for Claude Desktop with the following script and follow the instructions to add it to your Claude Desktop configuration:

cd /path/to/weconnect_mvp
./scripts/create_claude_config.sh

Reload Claude Desktop and ask questions like:

• "What vehicles are available?"
• "Show me my car's battery status"
• "Are my doors locked?"

Example Usage

Check battery status and state of charge:

Get complete vehicle status:

Check vehicle position:

Start charging session:

Interactive demo video:

---

GitHub Copilot (VS Code) Integration

Generate your configuration for GitHub Copilot with the following script and follow the instructions to add it to your VS Code settings:

cd /path/to/weconnect_mvp
./scripts/create_github_copilot_config.sh

Restart VS Code and verify installation by typing /list in Copilot Chat. Look for tools starting with mcp_weconnect_

Example Usage

Prepare for a trip - check battery, charging status, doors, and location:

Interactive demo video:

---

Microsoft Copilot Desktop Integration (untested)

Generate your configuration for Microsoft Copilot Desktop with the following script:

cd /path/to/weconnect_mvp
./scripts/create_copilot_desktop_config.sh

Copy the configuration file to Microsoft Copilot Desktop's config directory:

mkdir -p ~/Library/Application\ Support/Microsoft/Copilot
cp tmp/copilot_desktop_mcp.json ~/Library/Application\ Support/Microsoft/Copilot/mcp.json

Restart Microsoft Copilot Desktop completely and test

---

Other AI Tools (Cline)

The server uses the standard MCP protocol and works with all MCP-compatible tools.

Cline (VS Code Extension) - Configuration in .vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "weconnect": {
      "command": "python",
      "args": [
        "-m",
        "weconnect_mcp.cli.mcp_server_cli",
        "/path/to/your/config.json"
      ],
      "env": {
        "PYTHONPATH": "/path/to/weconnect_mvp/src"
      }
    }
  }
}

---

HTTP Mode for API Access

You can also start the server in HTTP mode for programmatic access or local testing of the cloud setup:

MCP_API_KEY=your-secret-key \
VW_USERNAME=your@email.com \
VW_PASSWORD=yourpassword \
VW_SPIN=1234 \
./scripts/start_server_http.sh 8080

The server will then be available at http://localhost:8080.

• MCP endpoint: http://localhost:8080/mcp
• Health check: http://localhost:8080/health

---

Cloud Deployment

The server ships with a Dockerfile and supports full cloud deployment, enabling connections from web-based AI services such as ChatGPT, Claude.ai, or any other MCP-compatible client.

Architecture

In HTTP/cloud mode the server starts two things independently:

1. HTTP server starts immediately → cloud health checks pass right away
2. VW OAuth login runs in the background (takes up to 30 s) → /health reports "ready": false until complete, then "ready": true

Tools called before the VW adapter is ready return a friendly "Server is still starting" error instead of crashing.

Option A: Railway (recommended)

Railway is a platform-as-a-service that builds and runs your Docker container automatically. It detects the Dockerfile and railway.toml in this repo with zero configuration.

Step 1 – Install Railway CLI and log in

brew install railway     # macOS; see https://docs.railway.com/guides/cli for other OSes
railway login

Step 2 – Create project and deploy

cd /path/to/weconnect_mvp
railway init             # creates a new Railway project linked to this directory
railway up --detach      # builds the Docker image and deploys it

Step 3 – Set secret environment variables
Never put credentials in the repository. Set them in the Railway dashboard instead:

railway variables set VW_USERNAME="your@email.com"
railway variables set VW_PASSWORD="yourpassword"
railway variables set VW_SPIN="1234"
railway variables set MCP_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"

Or go to: railway.com → your project → service → Variables

Step 4 – Get the public URL

railway domain           # e.g. https://weconnectmcp-production.up.railway.app

Step 5 – Verify

curl https://<your-subdomain>.up.railway.app/health
# → {"status": "ok", "ready": true, "service": "weconnect-mcp"}

Every git push followed by railway up redeploys the service.

---

Option B: Docker (local or any host)

Local test with Docker Compose:

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

The server is then available at http://localhost:8080.

Manual Docker run:

docker build -t weconnect-mcp .
docker run -p 8080:8080 \
  -e VW_USERNAME="your@email.com" \
  -e VW_PASSWORD="yourpassword" \
  -e VW_SPIN="1234" \
  -e MCP_API_KEY="your-secret-key" \
  weconnect-mcp

---

Environment Variables (Cloud / Docker)

Credentials and the API key are passed via environment variables — never put them in the repository:

Variable	Required	Description
VW_USERNAME	✅	VW WeConnect account e-mail
VW_PASSWORD	✅	VW WeConnect account password
VW_SPIN	✅	4-digit S-PIN
MCP_API_KEY	✅	Bearer token clients must send for authentication
PORT	auto	HTTP port (Railway injects this automatically; default: 8080)
CORS_ORIGINS	optional	Comma-separated allowed origins (default: *)

Generate a strong API key:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

---

Connecting AI Clients to the Cloud Server

Once deployed, point any MCP-compatible client at your public URL:

• MCP endpoint: https://<your-host>/mcp
• Authentication: HTTP header Authorization: Bearer <MCP_API_KEY>

Claude.ai:
Settings → Integrations → Add MCP Server → enter URL and header

ChatGPT Custom GPT:
Configure → Actions → select MCP → enter URL and Authorization: Bearer <key>

GitHub Copilot (VS Code) via remote server:
Add to .vscode/mcp.json:

{
  "servers": {
    "weconnect-cloud": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_API_KEY>"
      }
    }
  }
}

---

Security Notes for Cloud Deployment

⚠️ Always set MCP_API_KEY – without it the server runs unauthenticated
⚠️ Never commit .env or src/config.json – both are gitignored
⚠️ Rotate the key if it is ever exposed (e.g. accidentally pasted into a chat)
⚠️ The /health endpoint is intentionally unauthenticated (required for health checks)

Testing

Run the test suite with:

# Run all tests (including slow real API tests)
./scripts/test.sh

# Run only fast mock tests (skip real API tests - recommended for CI/CD)
./scripts/test.sh --skip-slow

# Run with verbose output
./scripts/test.sh --skip-slow -v

# Show help
./scripts/test.sh --help

Test Structure:

• 197 fast mock tests - Run in ~4 seconds, no VW credentials needed
• 18 slow real API tests - Require valid VW account in src/config.json

For detailed test documentation, see tests/README.md

---

Additional Documentation

• scripts/README.md - All available scripts and how to use them
• scripts/lib/README.md - Python detection library documentation
• tests/README.md - Test suite overview
• CONTRIBUTING.md - Contribution guidelines

---

Development Notes

• For development, always use a virtual environment and install in editable mode
• The CLI scripts activate the virtual environment automatically
• Main package source is under src/

Publication Readiness Agent

The project includes a custom GitHub Copilot agent to ensure publication readiness. This agent verifies:

• ✅ Code documentation quality (docstrings, type hints)
• ✅ README.md completeness
• ✅ License file presence
• ✅ Unit test coverage
• ✅ CLI scripts documentation

Usage:

# Via GitHub Copilot
@workspace /agent publication-readiness Run publication check

# Or follow the manual checklist
cat .github/agents/publication-readiness.md

For more information, see .github/agents/README.md.

Security Best Practices

⚠️ Never commit config.json or .env with your VW credentials!
⚠️ Add src/config.json to .gitignore if not already done
⚠️ The token store (default: /tmp/tokenstore) contains session tokens - keep it secure
⚠️ Use environment variables for sensitive data in production
⚠️ Always set MCP_API_KEY when running in HTTP mode on a public network
⚠️ Rotate MCP_API_KEY immediately if it was ever accidentally exposed
⚠️ The /health endpoint is intentionally unauthenticated (required for Railway / Docker health checks)

---

Known Limitations

1. No license plate data (VW API limitation): As of February 2026, the VW WeConnect API does not provide license plate information. All vehicles will show license_plate: null. This is a limitation of Volkswagen's official API, not this server.
2. First start takes time: VW API login can take 10-30 seconds
3. VW API rate limiting: Too many requests may be blocked
4. Token expiration: After a few hours, re-authentication is required

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md and follow the code of conduct.

---

License

This project is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0) — see LICENSE.txt for details or visit http://creativecommons.org/licenses/by-sa/4.0/

---

Credits

This project is built on top of the excellent CarConnectivity library by Till Steinbach. CarConnectivity provides the core functionality for connecting to Volkswagen's WeConnect API and handling vehicle data retrieval.

---

Additional Resources

• MCP Specification
• FastMCP Documentation