WidgetDash

WidgetDash MCP 服务

让 AI Agent 将任意数字显示在你的 iPhone 上。

WidgetDash 可以在 iPhone 主屏幕小组件、锁定屏幕小组件和实时活动中显示任意服务的数据。这个 模型上下文协议 服务可让 Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端将数据推送到你的小组件，并读取其中的数据。你只需提出要求：

“把我的 Stripe MRR 显示在 iPhone 小组件上。”

所需内容

1. 免费的 WidgetDash iOS 应用：https://apps.apple.com/us/app/widgetdash/id6761054679，并在主屏幕或锁定屏幕上添加一个 WidgetDash 小组件。
2. 你的 API 密钥。前往 https://widgetdash.app/app 获取。
   • 写入密钥：允许 Agent 创建和更新小组件数据。
   • 读取密钥（可选）：只读访问权限。如果不填写，读取工具会使用写入密钥。
3. Node.js 18 或更高版本（自带 npx）。

设置

Claude Code

claude mcp add widgetdash -e WIDGETDASH_WRITE_KEY=your-write-key -- npx -y widgetdash-mcp

Claude Desktop

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置），然后重启 Claude Desktop：

{
  "mcpServers": {
    "widgetdash": {
      "command": "npx",
      "args": ["-y", "widgetdash-mcp"],
      "env": {
        "WIDGETDASH_WRITE_KEY": "your-write-key",
        "WIDGETDASH_READ_KEY": "your-read-key"
      }
    }
  }
}

Cursor

将以下内容添加到 ~/.cursor/mcp.json（适用于所有项目），或添加到 .cursor/mcp.json（适用于单个项目）：

{
  "mcpServers": {
    "widgetdash": {
      "command": "npx",
      "args": ["-y", "widgetdash-mcp"],
      "env": { "WIDGETDASH_WRITE_KEY": "your-write-key" }
    }
  }
}

其他能够启动 stdio 服务的 MCP 客户端也可以使用相同方式。命令为 npx -y widgetdash-mcp，密钥需填写在下方的环境变量中。

环境变量

变量	必填	说明
WIDGETDASH_WRITE_KEY	写入时必填	从 https://widgetdash.app/app 获取的写入密钥。push_metrics、push_number 和 delete_source 需要此密钥。
WIDGETDASH_READ_KEY	否	读取密钥。list_sources 和 get_widget_data 会使用此密钥；如果未设置，则使用写入密钥。
WIDGETDASH_API_URL	否	API 基础 URL。默认值：https://api.widgetdash.app。

示例提示词

• “把我的 Stripe MRR 显示在 iPhone 小组件上。”（Agent 使用 Stripe 工具读取数字，然后调用 push_number。）
• “在锁定屏幕小组件上显示我仓库今天的 GitHub stars、未解决的 issues 和未合并的 PR。”
• “创建一个名为 ‘Server’ 的小组件，其中 CPU 使用进度条显示，运行时间以数字显示，并带有绿色的 ‘Healthy’ 状态徽章。”
• “每次完成构建后，将 ‘CI’ 小组件的状态设为 Passing 或 Failing。”
• “我的 WidgetDash 小组件现在显示什么？”
• “从我的小组件中移除旧的 ‘test’ 来源。”

工具

工具	功能
push_number	设置某个来源中的一个值，例如 MRR = $12,400。该来源中的其他指标保持不变。系统会按标签匹配指标。如果来源尚不存在，则会创建。
push_metrics	创建或更新来源：标题（display_name）、SF Symbol icon、category、sort_order（仅适用于新来源；可在应用中重新排序）以及完整的 metrics 列表。此列表会替换来源当前的指标。
list_sources	列出你的来源（键、标题、图标、隐藏或显示状态），并显示你的套餐允许的来源数量。免费套餐允许 5 个。
get_widget_data	显示小组件当前内容：所有已启用来源及其指标和上次更新时间，也可显示单个来源。
delete_source	永久删除某个来源，并结束其所有实时活动。

指标

每个指标都有 label、value、可选的 type、可选的 color 和可选的 wide：

• type 设置小组件显示数值的方式：

  • number：大号粗体数字。
  • text：普通字符串。
  • status：彩色徽章。
  • progress：进度条。数值必须介于 0 到 100 之间，末尾的 % 会自动移除。
  • percentage：紧凑的百分比文本。
  • timestamp：某个时间点，显示为实时相对时间，例如“8 小时前”。请发送 ISO 8601 时间（2026-10-23T05:00:00Z）或 Unix 纪元秒数。读取时会显示相对时间和精确时间。

  如果省略 type，看起来像数字的值（42、$12,400、3.5%）会被设为 number，其他值则会被设为 text。使用 push_number 时，现有指标会保留当前的类型、颜色和 wide；来源中的其他指标则会按原存储方式重新发送：时间戳保留精确时间，而由来源颜色规则选定的颜色仍由这些规则控制。

• color：green、red、yellow、blue、gray、orange、purple 或 cyan。

• wide：true 会让该指标在 Large 小组件（iOS 应用 1.8 或更高版本）中独占一整行，适合显示标题等较长文本。同一行的其他文本最多显示两行。将宽指标放在最后，以便其他指标保持在同一行。

• icon：任意 SF Symbol 名称，例如 dollarsign.circle.fill、chart.bar.fill、server.rack 或 heart.fill。

省略的字段（display_name、icon、category、raw_data）会保留当前值。sort_order 只会为新来源指定位置；来源创建后，其顺序以应用中设置的为准，因此 Agent 无法撤销该设置。

安全性

• 写入密钥只能写入你自己的小组件数据，无法访问其他用户的数据或你账户的账单信息。
• 密钥仅放在发往 WidgetDash API 的请求的 Authorization 标头中。服务器绝不会记录密钥，也会将其从返回的任何错误文本中移除。
• 请像对待密码一样保护写入密钥。如果密钥泄露，请前往 https://widgetdash.app/app 轮换密钥。
• 服务器只会与 WIDGETDASH_API_URL 通信，其默认值为 https://api.widgetdash.app。

开发

npm install
npm run build        # compiles src/ to dist/
npm test             # builds, then runs the end-to-end tests

npm test 会通过标准输入/输出上的真实 MCP 客户端，针对 WidgetDash API 的内存模拟（test/mock-api.mjs）运行所有工具。它不需要网络或密钥，也绝不会连接生产环境。

如需交互式试用，请运行 npx @modelcontextprotocol/inspector node dist/index.js。

MCP Registry

server.json 是 官方 MCP Registry 中名称为 io.github.purian/widgetdash-mcp 的条目，遵循架构 2025-12-11。package.json 中的 mcpName 字段必须与该名称一致，才能通过 npm 所有权验证。**状态：草稿。**该条目尚未发布，且注册表仍处于预览阶段，因此运行 mcp-publisher publish 前，请先根据当前架构检查 server.json。

许可证

MIT © WidgetDash