Vivint安全系统MCP服务器
FastMCP服务器，通过/MCP端点的Streamable HTTP，通过模型上下文协议（MCP）公开对Vivint家庭安全系统的只读访问。
重要提示：此集成使用非官方的反向工程API（vivinpy）。Vivint没有官方公开的API。使用风险由您自行承担，并请查看您的服务条款。
特性
MCP客户端暴露了八个只读工具：
- get_system_status——总体系统武装状态和元数据
- get_all_devices--完整的设备清单
- get_security_sensors--运动/门窗/烟雾/一氧化碳/洪水传感器
- get_cameras--相机状态和功能
- get_locks--智能锁状态和电池电量
- get_thermostats--气候数据和设定值
- get_recent_events--最近的活动快照
- get_device_health--电池/在线/注意力摘要
终结点基路径：/mcp（客户端必须包含此路径）。
先决条件
- Python 3.13+
- Vivint帐户（建议使用专用的最低权限用户）
- Node.js（通过npx用于MCP检查器）
- 可选：Cloudflared（暴露您的本地服务器）
- macOS、Linux或Windows。下面的命令使用macOS/zsh模式。
快速启动（本地）
- 克隆并进入项目
cd /Users/brad/GitHub
# Or your workspace directory
# git clone mcp-server-template
cd mcp-server-template- 创建环境并安装依赖项
选项A:venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt备选案文B：县
conda create -n mcp-server python=3.13 -y
conda activate mcp-server
pip install -r requirements.txt- 配置环境
cp .env.example .env
# Edit .env and set at minimum:
# VIVINT_USERNAME=your_email@example.com
# VIVINT_PASSWORD=your_password- 启用身份验证（推荐）
生成一个强HMAC密钥并将其添加到.env中：
python src/generate_token.py --type secret
# Copy the printed AUTH_SECRET=... into your .env
# Ensure AUTH_ENABLED=true, AUTH_TYPE=jwt, JWT_ALGORITHM=HS256生成一个短期JWT用于本地测试：
python src/generate_token.py --type token --hours 24 --subject local-dev- 启动服务器
python src/server.py
# Endpoint: http://localhost:8000/mcp- 使用MCP检查员进行测试
npx @modelcontextprotocol/inspector然后连接：
- 传输：流式HTTP
- 网址：http://localhost:8000/mcp
- 如果AUTH_ENABLED=true：添加标题授权：承载\
示例.env
根据需要复制/粘贴和编辑值。不要提交此文件。
# Environment
ENVIRONMENT=development
PORT=8000
# HOST optional; defaults internally (container vs. strict local)
# HOST=*******
# Logging / debug
DEBUG_MODE=false
LOG_LEVEL=INFO
# Vivint credentials (required)
VIVINT_USERNAME=your_email@example.com
VIVINT_PASSWORD=your_password
# If you have multiple systems, set a specific one
# VIVINT_SYSTEM_ID=
# Session management (seconds)
SESSION_REFRESH_INTERVAL=900
TOKEN_REFRESH_INTERVAL=18000
# Authentication (recommended in all environments)
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
# 2FA/MFA
# VIVINT_MFA_CODE=123456
VIVINT_REFRESH_TOKEN_FILE=.vivint_tokens.json
VIVINT_MFA_AUTO_WAIT=false
# OAuth (optional)
# OAUTH_CLIENT_ID=
# OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,http://localhost:3000/callback,http://localhost:8080/callback
OAUTH_DISABLE_NEW_CLIENTS=false
# CLOUDFLARE_TUNNEL_URL=https://your-tunnel.trycloudflare.com
# Rate limiting for login endpoints
RATE_LIMIT_ENABLED=true
RATE_LIMIT_LOCKOUT_MINUTES=5
RATE_LIMIT_MAX_ATTEMPTS=1笔记：
- 服务器绑定到HOST和PORT（提供默认值）。对于容器，建议使用bind-all；对于严格的本地，请使用环回地址。代码中的默认HOST已被编辑（\*\*\*\*\*\*）。
- 所有URL都必须包含/mcp基路径。
身份验证选项
JWT（HMAC，HS256）——建议用于单用户/本地
- 生成secret：python src/Generate_token.py--键入secret
- 配置.env:AUTH_ENABLED=true，AUTH_TYPE=jwt，jwt_ALGORITHM=HS256，AUTH_SECRET=。..
- 创建令牌：python src/generate_token.py--类型令牌--24小时--主题本地开发
- 验证令牌：python src/generate_token.py--验证“"
- 与检查员一起使用：授权：持有人
JWT（RSA，RS256）——多客户端
- 生成密钥：python src/Generate_token.py--键入密钥对
- 配置.env:JWT_PRIVATE_KEY、JWT_PUBLIC_KEY、JWT_算法=RS256
- 使用私钥（相同的脚本）生成令牌，并使用公钥进行验证。
OAuth 2.0——可选
- 生成客户端：python src/Generate_oauth_credentials.py
- 确保OAUTH_REDIRECT_URIS包括https://claude.ai/api/mcp/auth_callback（对于Claude）和任何本地回调。
- 启动服务器，并使用服务器的OAuth端点完成流程。在生产环境中，考虑将OAUTH_DISABLE_NEW_CLIENTS设置为true。
禁用身份验证（仅限开发）
# In .env
AUTH_ENABLED=false警告：如果您的服务器可以从互联网访问，请不要禁用身份验证。
2FA/MFA设置和令牌持久性
互动（推荐）
python setup_mfa.py它的作用：
- 需要时提示输入新的6位代码
- 将刷新令牌保存到VIVINT_refresh_TOKEN_FILE（默认值：.VIVINT_tokens.json）
- 验证连接
非交互式（一次性）
export VIVINT_MFA_CODE=123456
python src/server.py验证
python test_mfa.py令牌文件安全：将.vivint_tokens.json视为机密并限制权限（chmod 600）。
运行和调试
开始：
python src/server.py显式主机/端口：
HOST=********* PORT=8000 python src/server.py详细日志：
DEBUG_MODE=true LOG_LEVEL=DEBUG python src/server.py调试终结点（如果可用）：/Debug/oauth要求Debug_MODE=true。
MCP检验员测试
- 启动：npx@modelcontextprotocol/inspector
- 传输：流式HTTP
- 网址：http://localhost:8000/mcp
- 如果启用了auth：添加授权：承载
- 尝试工具：get_system_status、get_all_devices、get_device_health
Cloudflare 隧道（可选）
如果你想在不打开端口的情况下通过互联网进行测试：
repo中的辅助脚本：
./start_tunnel.sh # Starts a Quick Tunnel, prints public URL and saves it to .mcp_public_url
./tunnel_status.sh # Shows status and tests the endpoint
./stop_tunnel.sh # Stops the tunnel and cleans upOAuth重定向URI可以自动更新：
python update_oauth_uris.py --auto-tunnel手动替代方案：
cloudflared tunnel --url http://localhost:8000
# Your MCP endpoint is: https://.trycloudflare.com/mcp部署以渲染
使用上面的按钮或设置一个运行以下内容的Web服务：
- 内部版本：pip install-r requirements.txt
- 开始：python src/server.py
环境变量（最小值）：
- 环境=生产
- AUTH_ENABLED=真
- AUTH_TYPE=jwt（或oauth）
- 对于JWT HS：AUTH_SECRET=，JWT_算法=HS256
- 对于JWT RS：JWT_PRIVATE_KEY、JWT_PUBLIC_KEY、JWT_算法=RS256
- VIVINT_用户名，VIVINT_密码
- 可选：VIVINT_SYSTEM_ID，LOGLEVEL=警告/错误
您的端点将是：https://.onrender.com/mcp
工具参考
- get_system_status（）→{武装、武装状态、is_disarmed、is_armed_stay、is_armd_away、system_id、panel_id、panel_name、时间戳…}
- get_all_devices（）→\[{id、名称、类型、panel_id、system_id、状态、is_online、电池级别、last_update_time、…}\]
- get_security_sensors（）→\[{id、name、sensor_type、已触发、已绕过、zone_id、…}\]
- get_cameras（）→\[{id、名称、分辨率、夜视、运动检测、rtsp_available，…}\]
- get_locks（）→\[{id，name，locked，tamper_status，battery_level，last_operated_at，…}\]
- get_thermostats（）→\[{id、名称、当前温度、目标温度、加热点、冷却点、模式…}\]
- get_recent_events（小时=24）→ 〔｛id、类型、描述、时间戳、设备id、设备名称｝〕
- get_device_health（）→{总设备、在线设备、离线设备、低电池设备、设备_需求_关注，…}
返回字段是尽力而为的，取决于您的帐户/设备；错误以{error，timestamp}的形式返回。
建筑
核心文件
- src/server.py——FastMCP应用程序、身份验证设置（JWT/OAuth）、工具注册、/mcp上的HTTP传输
- src/vivint_client.py——vivintpy包装器、会话生命周期、MFA处理
- src/token_manager.py——安全令牌持久性和验证
- src/config.py——环境变量解析与验证
- setup_mfa.py、test_mfa.py——交互式mfa入职和验证
- start_tunnel.sh、tunnel_status.sh、stop_tunnell.sh--Cloudflared帮助程序
- render.yaml--渲染部署配置
会议记录
- 会话会定期刷新；代币自动刷新~5-6小时
- 设备和状态形状来自生动，可以向上游变化
故障排除
认证
- “需要AUTH_SECRET”→ 为HS\*添加AUTH_SECRET，为RS添加JWT_PUBLIC_KEY\*
- “需要MFA”→ 导出VIVINT_MFA_CODE或运行setup_MFA.py
- OAuth重定向不匹配→ 确保确切的URL在OAUTH_REDIRECT_URIS中，重新启动服务器
连接性
- 检查员无法连接→ 服务器正在运行？端口正确吗？URL是否包含/mcp？
- 渲染502→ 确保容器的HOST/PORT正确；环境=生产
设备
- 无设备→ 确认帐户/系统访问权限；当存在多个系统时，设置VIVINT_SYSTEM_ID
费率限制
- 登录已锁定→ 调整RATE_LIMIT\_\*或等待锁定到期
调试
- DEBUG_MODE=true LOGLEVEL=详细日志的调试
- /debug/oauth（如果启用）检查oauth配置
安全
- 在生产环境中保持AUTH_ENABLED=true
- 定期旋转AUTH_SECRET/键
- 使用专门的Vivint用户
- 不要提交.env或令牌文件；将.vivint_tokens.json视为秘密（chmod 600）
- 在生产环境中保持DEBUG_MODE=false
- 请注意，vivintpy是非官方的，可能会在没有通知的情况下中断
限制和免责声明
- 通过vivingpy非官方使用API（无担保；可能会破损）
- 只读访问；无设备控制
- 可能违反供应商条款——负责任地继续
许可证
麻省理工学院——见许可证。
本项目不隶属于Vivint或得到Vivint的认可。