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

Related MCP server: mcp-teslamate-fleet

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 the project in editable mode (pip install -e .)

• ✅ 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 -e .

For running tests locally, install test extras:

pip install -e ".[test]"

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 8089

CLI Parameters

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

Example:

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

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:

Command tools (10) — control vehicle remotely:

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.

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"
      ]
    }
  }
}

HTTP Mode for API Access

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

Port strategy for HTTP mode

• Railway / cloud: Railway injects $PORT automatically (default in image: 8080). No manual configuration needed.

• Local Docker: Container runs internally on 8080; docker-compose.yml maps host port 8089 → container port 8080. Access via http://localhost:8089.

• Local CLI (no Docker): start_server_http.sh defaults to port 8089. Use a different port only when that port is already in use.

Using a non-standard port (8089) for local Docker/CLI avoids conflicts when multiple MCP servers are running side by side.

Via script (recommended):

# Reads credentials from .env automatically
./scripts/start_server_http.sh          # starts on http://localhost:8089 (default)
./scripts/start_server_http.sh 8090     # override port if needed

Inline (manual override):

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

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

• MCP endpoint: http://localhost:8089/mcp

• Health check: http://localhost:8089/health

Connecting AI clients (VS Code Copilot, Claude Code) to a local HTTP server:

// VS Code: %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "weconnect": {
      "type": "http",
      "url": "http://localhost:8089/mcp",
      "headers": { "Authorization": "Bearer <YOUR_MCP_API_KEY>" }
    }
  }
}

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "weconnect": {
      "url": "http://localhost:8089/mcp",
      "headers": { "Authorization": "Bearer <YOUR_MCP_API_KEY>" }
    }
  }
}

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:8089.

Environment Variables (Cloud / Docker)

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

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