home / mcp / vivint mcp server

Vivint MCP Server

Vivint Security System MCP Server - Read-only access to your Vivint home security system via FastMCP over HTTP

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "bradmb-vivint-mcp": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "HOST": "<HOST>",
        "PORT": "8000",
        "AUTH_TYPE": "jwt",
        "JWT_ISSUER": "vivint-mcp-server",
        "AUTH_SECRET": "replace-with-strong-secret",
        "ENVIRONMENT": "development",
        "AUTH_ENABLED": "true",
        "JWT_ALGORITHM": "HS256",
        "VIVINT_PASSWORD": "••••••••",
        "VIVINT_USERNAME": "[email protected]",
        "VIVINT_SYSTEM_ID": "<VIVINT_SYSTEM_ID>"
      }
    }
  }
}

You can run a dedicated MCP server that exposes read‑only access to your Vivint home security data over the Model Context Protocol. This server serves information about system status, devices, sensors, cameras, locks, thermostats, recent events, and device health, all via a single /mcp endpoint you can connect to from MCP clients.

How to use

Start the server locally and connect with an MCP client to read live Vivint data. Use a Streamable HTTP transport and point your client to the /mcp endpoint. If you enable authentication, provide a Bearer token with each request. You can test access with the MCP Inspector tool by pointing it to http://localhost:8000/mcp and supplying a token when auth is enabled. You will be able to query eight read‑only tools that return current system status, devices, sensors, cameras, locks, thermostats, recent events, and overall device health.

How to install

# Prerequisites: Python 3.13+, Node.js for MCP Inspector, optionally Cloudflared for tunneling

# 1) Clone and enter the project
cd /Users/you/workspace
# git clone <your-remote> vivint-mcp
cd vivint-mcp

# 2) Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3) Prepare environment variables
cp .env.example .env
# Edit .env and set at minimum:
# [email protected]
# VIVINT_PASSWORD=your_password

# 4) Enable authentication (recommended)
python src/generate_token.py --type secret
# Copy the printed AUTH_SECRET=... into your .env and set:
# AUTH_ENABLED=true, AUTH_TYPE=jwt, JWT_ALGORITHM=HS256

# 5) Start the server
python src/server.py
# Endpoint: http://localhost:8000/mcp

# 6) Test with MCP Inspector (optional)
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: http://localhost:8000/mcp
# If AUTH_ENABLED=true: add header Authorization: Bearer <your_jwt>

Configuration and security

You configure and run the server using environment variables in a .env file. The example shows how to enable authentication, set Vivint credentials, and control session behavior. Store sensitive tokens and credentials securely and do not commit .env or token files. For production, keep DEBUG_MODE=false and rotate secret keys regularly.

# Example environment values (edit as needed)
ENVIRONMENT=development
PORT=8000
HOST=localhost
DEBUG_MODE=false
LOG_LEVEL=INFO
[email protected]
VIVINT_PASSWORD=your_password
VIVINT_SYSTEM_ID=
SESSION_REFRESH_INTERVAL=900
TOKEN_REFRESH_INTERVAL=18000
AUTH_ENABLED=true
AUTH_TYPE=jwt
JWT_ALGORITHM=HS256
AUTH_SECRET=replace-with-strong-secret
JWT_ISSUER=vivint-mcp-server
JWT_AUDIENCE=vivint-mcp-client
TOKEN_EXPIRY_HOURS=24
VIVINT_REFRESH_TOKEN_FILE=.vivint_tokens.json
VIVINT_MFA_AUTO_WAIT=false
OAUTH_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,http://localhost:3000/callback
OAUTH_DISABLE_NEW_CLIENTS=false
RATE_LIMIT_ENABLED=true
RATE_LIMIT_LOCKOUT_MINUTES=5
RATE_LIMIT_MAX_ATTEMPTS=1

Additional notes

All URLs must include the /mcp base path. The endpoint used for local testing is http://localhost:8000/mcp. Use a dedicated Vivint user account to minimize risk, and treat the token and credentials as secrets. If you run into authentication issues, verify that AUTH_SECRET is set for HS* algorithms or that your public key is configured for RS*. MFA may be required depending on your Vivint account settings, and you can run the interactive MFA setup to persist refresh tokens.

Troubleshooting

If the MCP inspector cannot connect, confirm that the server is running and listening on the expected host and port, and that the URL includes /mcp. For internet exposure, consider a Cloudflare tunnel or Render deployment as described, and ensure the environment variables for authentication are correctly set. When devices do not appear, confirm access to the Vivint account and, if multiple systems exist, set VIVINT_SYSTEM_ID to target the correct system.

Security considerations

Maintain a dedicated Vivint user with least privilege, enable authentication in all exposed environments, rotate secrets and keys regularly, and do not share tokens. The MCP server relies on an unofficial Vivint API wrapper, so expect potential breakages or changes and monitor for updates accordingly.

Tool reference

The server exposes read‑only tools that return current system data and state. Available tools include get_system_status, get_all_devices, get_security_sensors, get_cameras, get_locks, get_thermostats, get_recent_events, and get_device_health.

Available tools

get_system_status

Returns overall armed state, metadata, and panel identifiers

get_all_devices

Provides a complete inventory of devices with their states

get_security_sensors

Lists motion, door/window, smoke/CO, and flood sensors and their status

get_cameras

Fetches camera status and capabilities

get_locks

Shows smart lock states and battery levels

get_thermostats

Returns climate data and setpoints

get_recent_events

Gathers recent activity snapshots

get_device_health

Provides battery, online, and attention summaries