
背景
因为爱人在外地工作,每个周末都是特斯拉的两地通勤,对于是否平安到达的判断就是不时的拿出手机打开特斯拉的app查看车辆的位置。在全面ai、agent的情况下,肯定是可以让ai把这个事情搞定的,帮我盯好行程位置。
现在在 Telegram 里问一句「车停在哪,开到临沂要多久」,它会先查车,再交给高德算路线。「如果进入某某区域,就及时发信息给我」Hermes就替我把整个过程守护了起来。
我的助手是 Hermes Agent,部署在群晖 NAS 的 Docker 里,通过 Telegram 和我对话,模型请求统一走 LiteLLM。Hermes 内置 MCP(Model Context Protocol)客户端,外部能力以 MCP Server 的形式接进来,工具会自动注册成 mcp_<服务名>_<工具名>。
这篇记录两件事:高德地图 MCP 的接入(十分钟搞定),以及特斯拉的接入(主线,涉及开发者注册、OAuth、自写 MCP 和几处踩坑)。文中所有密钥、车辆标识、域名和路径都做了替换。
一、高德地图 MCP 接入
高德官方提供远程 MCP 服务,走 Streamable HTTP,Hermes 里只需要加一个 url,不用装任何东西。
1. 申请 Key
在高德开放平台控制台创建应用、添加 Key,服务平台必须选「Web 服务」。选成 Web 端(JS)或移动端的 Key,调用时会报 USERKEY_PLAT_NOMATCH。个人开发者的免费额度,查吃饭的地方足够。
2. 写进 Hermes 配置
Hermes 的 MCP 配置在 config.yaml 的 mcp_servers 下:
mcp_servers:
amap:
url: "https://mcp.amap.com/mcp?key=<你的高德Key>"
timeout: 60改完在 Hermes 里执行 /reload-mcp,看到 mcp_amap_maps_around_search 这类工具就是接好了。可用的工具包括地址与坐标互转、天气、驾车/步行/骑行/公交路线、距离测量、关键词搜索、周边搜索和 POI 详情。
3. 使用要点
- Hermes 在 NAS 上,不知道你人在哪。提问要带位置,比如「我在泉城广场附近,找 1 公里内人均 100 以内的鲁菜馆」。
- 地名容易重名,带上城市或路名更准。
- Key 是明文写在 URL 里的,配置文件不要进公开的 Git 仓库。
二、特斯拉接入:设计与安全原则
路线是:特斯拉官方 Fleet API → 自写的只读 MCP Server → Hermes。动手之前,我先把安全边界定死,因为这件事的风险不在车本身,而在权限泄露和 AI 误操作。
高德走远程 HTTP,特斯拉走容器内的 stdio 子进程;token 文件只在 NAS 上,公钥站点只给特斯拉校验域名用。
Fleet API 没有转向、刹车、加速这类接口,影响不了行驶。真正要防的是三件事:
- token 泄露等于位置泄露:拿到 token 就能知道车在哪、人在哪、几点到家。如果还授了控车权限,对方能远程解锁。
- AI 误操作或被注入:模型可能把「车锁了吗」理解成「开锁」;读网页、邮件时也可能被藏在里面的指令带偏。
- 频繁唤醒:每次查位置都要车醒着,被轮询的话车无法休眠,停放掉电明显,API 也按次计费。
据此定下四条原则:
- 只授读权限:授权范围只要车辆信息和车辆位置,不要车辆命令;车上也不配对虚拟钥匙。即使 token 被盗,也控制不了车。
- 代码里不存在控车接口:MCP 只实现查询,不写解锁、空调、充电这些函数,从根上杜绝误操作。
- 唤醒在代码层面限制:默认完全禁止唤醒;需要时才打开,且两次唤醒至少间隔 30 分钟。不靠模型自觉。
- 自己部署,不用公共服务:MCP 跑在自己的 NAS 上,token 文件权限 600,不进 Git、不备份到云盘。
照这样配置,最坏的情况也只是「别人知道车在哪」,碰不到车本身。
三、开发者注册
国内车主走中国区:车是国内买的、账号在 tesla.cn,就必须在 developer.tesla.cn 单独建应用,需要 +86 手机号。中国区的认证服务器是 auth.tesla.cn,API 地址是 fleet-api.prd.cn.vn.cloud.tesla.cn,都和海外分开。
1. 客户端详细信息
| 字段 | 填法 |
|---|---|
| OAuth 授权类型 | 授权码和机器对机器(个人用户选这个) |
| 允许的源 URL | https://car.example.com,只写到域名 |
| 允许的重定向 URI | http://localhost:3000/callback,http 只允许本地主机 |
| 允许的返回 URL | 留空 |
重定向用本地地址的好处是:授权在自己电脑的浏览器里完成,回调地址不用暴露到公网。
2. 先把域名搭起来再填
第一次填源 URL 时报了「域无效」。原因是特斯拉会实时检查这个域名:要能解析、https 能打开、证书有效、域名里不能带 tesla 字样,也不能挂在反向代理(比如 Cloudflare 的橙色云朵)后面。
我在一台海外 VPS 上用 Caddy 起了个静态站,自动申请证书。顺手生成命令签名用的 P-256 密钥对,公钥放到特斯拉要求的固定路径:
mkdir -p /srv/car/.well-known/appspecific
openssl ecparam -name prime256v1 -genkey -noout -out ~/tesla-private-key.pem
openssl ec -in ~/tesla-private-key.pem -pubout \
-out /srv/car/.well-known/appspecific/com.tesla.3p.public-key.pem
chmod 600 ~/tesla-private-key.pem
docker run -d --name car-web --restart unless-stopped \
-p 80:80 -p 443:443 -v /srv/car:/srv -v caddy_data:/data \
caddy caddy file-server --root /srv --domain car.example.com公钥地址公开在互联网上没有问题,它本来就是给特斯拉验证用的。要保护的是私钥:它只放在 ~/,绝不能进网站目录。目录列表也不要打开。
3. API 和范围
只勾两项:车辆信息和车辆位置。个人资料、车辆命令、充电管理、能源产品一律不勾。范围以后可以在后台修改。
四、合作伙伴注册与 OAuth 授权
现成的 Tesla MCP 基本都写死了国际区的认证地址,直接用会失败。所以我先用 curl 把中国区流程走通,确认能拿到车辆数据,再写 MCP。
0. 变量
export CLIENT_ID="<开发者后台的 Client ID>"
export CLIENT_SECRET="<开发者后台的 Client Secret>"
export AUDIENCE="https://fleet-api.prd.cn.vn.cloud.tesla.cn"
export REDIRECT_URI="http://localhost:3000/callback" # 与后台完全一致1. 合作伙伴 token + 注册域名(一次性)
PARTNER_TOKEN=$(curl -s -X POST https://auth.tesla.cn/oauth2/v3/token \
--data-urlencode grant_type=client_credentials \
--data-urlencode client_id="$CLIENT_ID" \
--data-urlencode client_secret="$CLIENT_SECRET" \
--data-urlencode scope="openid vehicle_device_data vehicle_location" \
--data-urlencode audience="$AUDIENCE" | jq -r .access_token)
curl -s -X POST "$AUDIENCE/api/1/partner_accounts" \
-H "Authorization: Bearer $PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain":"car.example.com"}'2. 车主授权
浏览器打开下面的地址,登录并同意:
https://auth.tesla.cn/oauth2/v3/authorize?response_type=code&client_id=<Client ID>&redirect_uri=http://localhost:3000/callback&scope=openid%20offline_access%20vehicle_device_data%20vehicle_location&state=<随机串>授权后跳到 localhost,页面打不开是正常的。从地址栏复制 code= 后面的值,几分钟内换成 token:
curl -s -X POST https://auth.tesla.cn/oauth2/v3/token \
--data-urlencode grant_type=authorization_code \
--data-urlencode client_id="$CLIENT_ID" \
--data-urlencode client_secret="$CLIENT_SECRET" \
--data-urlencode code="$CODE" \
--data-urlencode redirect_uri="$REDIRECT_URI" \
--data-urlencode audience="$AUDIENCE" > tesla-token.json
chmod 600 tesla-token.jsontesla-token.json 里只有 token(access\_token 约 8 小时有效,外加 refresh\_token),没有车辆信息,这一点我一开始也搞混了。
3. 验证
ACCESS=$(jq -r .access_token tesla-token.json)
curl -s -H "Authorization: Bearer $ACCESS" "$AUDIENCE/api/1/vehicles" | jq返回里能看到车辆、access_type: OWNER 和 state: online/asleep,中国区流程就通了。趁车醒着,再用 vehicle_data?endpoints=location_data 确认能拿到坐标。
五、自写只读 MCP:tesla\_cn\_mcp.py
与其改别人的代码,不如写一个专门对接中国区的精简版:单个 Python 文件,基于官方 mcp SDK 的 FastMCP(同时兼容 SDK 1.x 和 2.x,2.x 里它改名叫 MCPServer),依赖只有 mcp 和 httpx。
四个工具,全部只读
| 工具 | 作用 | 会不会唤醒车 |
|---|---|---|
list_vehicles | 列出车辆和在线状态,VIN 自动打码 | 不会 |
vehicle_state | 查车是否醒着(online / asleep / offline) | 不会 |
vehicle_location | 高德坐标、高德地图链接、定位时间和距今分钟数 | 默认不会 |
vehicle_summary | 电量、续航(公里)、充电、锁车、门窗、哨兵、温度、里程 | 默认不会 |
token 自动刷新
access\_token 快过期时,脚本用 refresh\_token 换新的。特斯拉每次刷新都会轮换 refresh\_token,旧的立即作废,所以新 token 必须原子写回文件(先写临时文件再 os.replace,权限 600)。遇到 401 会强制刷新重试一次。
坐标转换
国内地图用 GCJ-02,GPS 是 WGS-84,直接放进高德会偏几百米。我不确定中国区 API 返回的是哪种,所以没有猜:自检模式会同时输出「转换后」和「原样」两个高德链接,打开看哪个和特斯拉 App 里的位置重合。实测是转换后的准,说明中国区返回的是标准 GPS 坐标。坐标系做成了环境变量 TESLA_COORD_SYSTEM,默认 wgs84。
唤醒限制写在代码里
工具说明里写了「只有用户明确要求才唤醒、不要循环调用」,但这是靠提示约束,模型偶尔会自作主张。所以又加了硬限制:
TESLA_ALLOW_WAKE默认false:无论模型怎么传参,代码都不发唤醒请求。- 打开后有
TESLA_WAKE_COOLDOWN_MIN(默认 30 分钟)冷却,记录写在 token 文件旁的.lastwake,重启也不清零。
用模拟的休眠车辆测过四种情况:禁用时传 wake=True 唤醒请求为 0;放开后第一次正常唤醒;30 分钟内第二次被拦;不传 wake 不唤醒。
自检模式
python3 tesla_cn_mcp.py --test 会依次列车辆、查状态,车醒着时再查位置、给出坐标校准链接和车辆概况。自检本身不会唤醒车辆。
六、部署到 NAS 上的 Hermes
1. 找到容器能访问的目录
docker inspect hermes-agent \
--format '{{range .Mounts}}{{.Source}} → {{.Destination}}{{println}}{{end}}'我的 Hermes 数据目录挂载在容器的 /opt/data,config.yaml 也在这里。在它下面建 tesla/ 子目录,放入脚本和 token 文件。
2. 检查文件、依赖和写权限
docker exec hermes-agent ls -l /opt/data/tesla/
docker exec hermes-agent python3 -c "import mcp, httpx; print('ok')"
docker exec hermes-agent sh -c 'touch /opt/data/tesla/.w && rm /opt/data/tesla/.w && echo writable'
docker top hermes-agent -o user,pid,args | head # 确认主进程用户能读 token 文件目录必须可写,因为每次刷新都要写回新的 refresh\_token。
3. 配置
mcp_servers:
tesla:
command: "/opt/hermes/.venv/bin/python3" # 用完整路径,原因见踩坑记录
args: ["/opt/data/tesla/tesla_cn_mcp.py"]
env:
TESLA_CLIENT_ID: "<Client ID>"
TESLA_TOKEN_FILE: "/opt/data/tesla/tesla-token.json"
TESLA_VEHICLE_ID: "<车辆 id>"
timeout: 90在 Telegram 里发 /reload-mcp,看到 mcp_tesla_vehicle_location 等工具就接好了。
4. token 只留一份
在 Mac 上自检用过的 token 文件,直接拷到 NAS 继续用,之后 Mac 上不要再运行。refresh\_token 刷新一次旧的就作废,两台机器各拿一份,迟早有一边失效。同理,不要备份 token 文件,旧备份恢复回来是失效的。真丢了,重新授权两分钟。
七、踩坑记录
| 现象 | 原因 | 解决 |
|---|---|---|
| 填源 URL 报「域无效」 | 域名还没搭起来,特斯拉会实时检查解析和证书 | 先用 Caddy 起好 https 静态站,再回来填 |
| 换完 token 找不到车辆信息 | token 文件只存凭证,车辆信息要另外调 /api/1/vehicles | 分清「拿钥匙」和「用钥匙查车」两步 |
Mac 上 pip: command not found | 新版 Python 不允许往系统环境装包 | python3 -m venv 建虚拟环境再装 |
mcp.server.fastmcp 导入失败 | mcp SDK 2.x 把 FastMCP 改名为 MCPServer | 两种导入都试,兼容 1.x 和 2.x |
| 重启后 Telegram 没反应 | Hermes 卡在连接 tesla MCP,约 5 分钟后放弃,期间消息无响应 | 修好 MCP 后 /reload-mcp;排查时可先注释掉这段配置 |
MCP 报 Connection closed | Hermes 启动子进程只传 env 里写的变量,不传 PATH,找不到 python3 | command 写容器内 Python 的完整路径 |
| 定位时间显示 1943 年 | 时间戳转换只处理了秒和毫秒两种单位 | 自动识别秒/毫秒/微秒/纳秒,不合理的结果直接标为无效,并返回原始值 |
排查 MCP 启动问题时,这条命令能模拟 Hermes 的启动方式(无 PATH),看到 exit=124 说明程序正常启动、在等请求:
docker exec hermes-agent env -i TESLA_CLIENT_ID=x TESLA_TOKEN_FILE=/opt/data/tesla/tesla-token.json \
timeout 5 /opt/hermes/.venv/bin/python3 /opt/data/tesla/tesla_cn_mcp.py; echo "exit=$?"定位时间那个 bug 是 Hermes 自己发现的:它注意到时间不对,明确说「无法证明坐标是新鲜的」,没有硬编一个结论。这也是给工具返回原始值和「距今分钟数」的原因。
八、总结
两个 MCP 接好后,Hermes 能把「车在哪」和「怎么去」串起来回答。车醒着时随时能查;车在休眠时它会如实说明,想查就先打开特斯拉 App 把车叫醒。
几点体会:
- 高德是一行配置的事,特斯拉是一条完整的链路:开发者应用、域名公钥、合作伙伴注册、OAuth、MCP、部署。中国区和海外完全分开,现成工具多半不能直接用。
- 安全靠代码,不靠提示。只读权限、不写控车函数、唤醒默认禁用,这些在代码和授权层面定死,比在工具说明里叮嘱模型可靠得多。
- 不确定的事情实测。坐标系和时间戳格式都没有猜,而是让工具把原始值和对比链接摆出来验证。
- token 维护很省心:access\_token 自动刷新,refresh\_token 只要隔段时间用一次就一直续着。只有长期不用、改密码或撤销授权时,才需要重新走一遍授权。