HealthyApps Help Center

连接到服务器

连接到 Health Auto Export 的 MCP 服务器，供本地网络上的 AI 客户端和脚本使用。

Last updated: July 14, 2026

本页目录

服务器连接指南

iOS 上的 MCP 服务器可让本地网络上的 AI 客户端和脚本查询你的健康数据。HTTP（Streamable MCP）是推荐的传输方式。 iOS 也支持 TCP，用于 Node 桥接方案。

客户端在你的 Mac 或同一网络上的其他设备上运行，并连接到 iPhone 上显示的端点。

概述

传输方式 端点
HTTP（推荐） http://{LAN_IP}:9000/mcp（启用 HTTPS 时为 https://）
TCP {LAN_IP}:9000（无身份验证）

将 {LAN_IP} 替换为服务器运行时服务器屏幕上显示的地址。

使用场景：

  • 将 Mac 上的 Claude Code、Codex、Cursor 或 VS Code 连接到 iPhone 上的健康数据
  • 为 Claude Desktop 等仅支持 stdio 的客户端使用 mcp-remote（iOS / LAN）
  • 从本地网络的脚本查询指标和运动数据（HTTP）
  • 通过 health-auto-export-mcp-server Node 桥接实现 TCP 集成

先决条件

  • iPhone 上运行 Health Auto Export（客户端连接期间应用必须保持在前台）
  • 高级订阅
  • HTTP： 来自服务器屏幕的 Bearer 令牌
  • iPhone 的本地网络权限
  • 客户端设备： 与 iPhone 处于同一 Wi‑Fi 或局域网；仅在使用 mcp-remote（iOS / LAN） 时才需要 Node.js

启动服务器

  1. 在 iPhone 上，使用侧边栏导航打开服务器
  2. 选择 HTTP（推荐）或 TCP
  3. 可选择启用使用 HTTPS（见下方说明）
  4. 点按启动服务器
  5. 复制端点 URL 和 Bearer 令牌

如果 Health Auto Export 进入后台，服务器会自动停止（HTTP 和 TCP 均如此）。

身份验证（HTTP）

所有 HTTP 请求都需要：

Authorization: Bearer <your-token>
  • 如认为有必要，可在服务器屏幕上重新生成令牌
  • 在纯 HTTP 下，令牌通过未加密的连接发送——请仅在受信任的网络上使用，或启用 HTTPS
  • 传统 TCP 没有身份验证（保持不变）

HTTPS (TLS)

启用使用 HTTPS 后，应用会生成一个私有的本地证书颁发机构（CA）以及由该 CA 签名的服务器叶证书。客户端必须先信任导出的 CA，才能通过 https:// 连接。

启用 HTTPS

  1. 使用侧边栏导航打开服务器视图
  2. 打开使用 HTTPS
  3. 点按导出 CA 证书，通过分享面板将 CA 文件 AirDrop 或保存到每台客户端设备
  4. 启动服务器——确认端点 URL 已切换为 https://

在客户端上信任 CA

在运行 AI 客户端的设备（通常是你的 Mac）上信任导出的 CA：

  1. 在 iPhone 的服务器屏幕上导出 CA
  2. 在客户端 Mac 的钥匙串访问中打开 PEM 文件
  3. 将信任 → 始终信任设置为对应选项

--use-system-ca 所需的 Node 最低版本

Node 桥接程序（mcp-remote）只能在 Node 满足以下条件时使用 NODE_OPTIONS=--use-system-ca：

Node 系列 最低版本
22.x 22.19.0
23.x 23.8.0
24.x 24.6.0
25+ 任意版本

在更低版本的 Node 上，请改为将 NODE_EXTRA_CA_CERTS 设置为桥接进程可读取的 PEM 路径。在不受支持的 Node 上使用 --use-system-ca 会导致进程无法启动。

信任范围： --use-system-ca 会信任整个系统钥匙串，而不仅是本应用的 CA。NODE_EXTRA_CA_CERTS 则将信任限定在单个 PEM 文件（用于旧版 Node 的回退方案）。该标志在 macOS/Windows 上有文档说明。

客户端类型 设置方式
Cursor、VS Code、Claude Code、Codex 在客户端 Mac 上设置钥匙串信任——使用服务器屏幕上的 https:// 端点
mcp-remote（iOS / LAN） 在运行 mcp-remote 的Mac的钥匙串中信任 CA。当 Node 满足最低版本要求时，代码片段会使用 NODE_OPTIONS=--use-system-ca；在更旧的 Node 上，请将 NODE_EXTRA_CA_CERTS 设置为可读的 PEM 路径
curl / 脚本 传入 --cacert /path/to/mcp-ca.pem，或设置 NODE_EXTRA_CA_CERTS

服务器屏幕会显示 CA 指纹，方便你验证导出的证书是否正确。

iOS 局域网 IP 变化时

当你的 iPhone 局域网 IP 变化时，应用会使用更新后的 Subject Alternative Names 重新生成叶证书，并重启 HTTPS 监听器。如果 IP 发生变化，请重新复制端点 URL。除非你通过关闭再开启 HTTPS 来重新生成 CA，否则 CA 证书保持不变。

HTTPS 端点示例

https://192.168.1.42:9000/mcp

请将主机部分替换为服务器屏幕上显示的值。

契约版本

版本 TCP 工具名称 说明
v1.1.0（默认） get_* 推荐用于新设置
v1.0.0 传统（health_metrics 等） Claude Desktop 兼容性更新 v1.0.0
v0.0.1 传统 最早的兼容版本

HTTP 始终使用 get_* 工具名称；契约版本仅影响架构默认值。

客户端配置

服务器屏幕为每种集成提供了可直接复制粘贴的代码片段。请使用其中显示的端点和令牌。请对照你的客户端版本核对格式。

以下示例均使用占位符局域网地址——请替换为服务器屏幕上显示的 iPhone 地址。

Claude Code（CLI）

在 Mac 上运行（需要 Claude Code CLI）：

HTTP：

claude mcp add --transport http health-auto-export \
  http://192.168.1.42:9000/mcp \
  --header "Authorization: Bearer <token>"

HTTPS（在 Mac 上导出并信任 CA 之后）：

claude mcp add --transport http health-auto-export \
  https://192.168.1.42:9000/mcp \
  --header "Authorization: Bearer <token>"

Claude Code / 项目文件（.mcp.json）

{
  "mcpServers": {
    "health-auto-export": {
      "type": "http",
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "health-auto-export": {
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "health-auto-export": {
      "type": "http",
      "url": "http://192.168.1.42:9000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Codex CLI（~/.codex/config.toml）

Codex 直接通过 Streamable HTTP 连接——不需要 Node.js 桥接。配置文件位于 ~/.codex/config.toml（全局）或受信任项目目录下的 .codex/config.toml。

CLI（推荐）：

export HAE_MCP_TOKEN="<token>"
codex mcp add health-auto-export \
  --url http://192.168.1.42:9000/mcp \
  --bearer-token-env-var HAE_MCP_TOKEN

手动配置 config.toml：

[mcp_servers.health-auto-export]
url = "http://192.168.1.42:9000/mcp"
bearer_token_env_var = "HAE_MCP_TOKEN"
enabled = true

在启动 Codex 之前，导出包含 Bearer 令牌的 HAE_MCP_TOKEN。设置完成后，在 Codex 会话中运行 /mcp 以验证服务器是否已连接。

如果你在 Health Auto Export 中重新生成了 Bearer 令牌，请更新 HAE_MCP_TOKEN 并重新运行 codex mcp add，或者移除后重新添加该服务器条目。

mcp-remote（iOS / LAN）

适用于无法直接通过 HTTP 连接的仅 stdio 客户端（例如 Claude Desktop）。需要在运行客户端的 Mac 上安装 Node.js。

  1. 在 iPhone 上启动服务器，并复制端点和令牌
  2. 在 Mac 上，选择服务器屏幕上的**mcp-remote（iOS / LAN）**并复制 JSON 代码片段，或将以下内容粘贴到客户端的 MCP 配置中（Claude Desktop → 设置 → Developer → Edit Config）：
{
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote@0.1.16",
    "http://192.168.1.42:9000/mcp",
    "--transport",
    "http-only",
    "--header",
    "Authorization: Bearer <token>"
  ]
}

启用 HTTPS 时：

  1. 从 iPhone 导出 CA，并在 Mac 的钥匙串访问中信任它（始终信任）
  2. 在 args 中使用 https://192.168.1.42:9000/mcp
  3. 当 Node 满足 --use-system-ca 的最低版本要求时（22.x 上为 22.19.0，23.x 上为 23.8.0，24.x 上为 24.6.0，25 及以上任意版本均可），添加：
"env": {
  "NODE_OPTIONS": "--use-system-ca"
}

在更旧的 Node 上，请改为将 NODE_EXTRA_CA_CERTS 设置为可读的 PEM 路径。更新配置后请重启 stdio 客户端。

减少启动延迟： npx -y 会在首次使用时下载 mcp-remote，并在缓存过期时重新检查，这可能造成数秒的延迟。全局预安装可以消除这一问题：

npm install -g mcp-remote@0.1.16

工具参数

日期格式

start 和 end 参数支持两种格式：

格式 示例 说明
yyyy-MM-dd 2026-06-13 起始日：午夜；结束日：23:59:59
yyyy-MM-dd HH:mm:ss Z 2026-06-13 00:00:00 +0000 显式指定时间和时区偏移

TCP

  • 端口 9000 上未加密、未经身份验证的 JSON-RPC
  • 使用契约 v1.0.0 搭配 Node 的 health-auto-export-mcp-server 桥接以获取传统工具名称
  • 使用契约 v1.1.0 获取 get_* TCP 工具名称（需另行更新 Node 桥接）

提示

  1. 在客户端连接期间，请将 Health Auto Export 保持在 iPhone 前台
  2. 如果怀疑令牌已泄露，请重新生成
  3. 在 iPhone 局域网 IP 变化后，重新复制端点 URL

聊天支持

通过设置 → 高级 → 导出事件日志导出应用事件日志以收集诊断信息。参阅应用事件日志指南。通过聊天支持或电子邮件分享生成的 zip 文件。