WidgetDash

WidgetDash MCP server

Let your AI agent put any number on your iPhone.

WidgetDash shows numbers from any service on iPhone Home Screen widgets, Lock Screen widgets and Live Activities. This Model Context Protocol server lets Claude Desktop, Claude Code, Cursor and other MCP clients push data to your widgets and read it back. You just ask:

"Put my Stripe MRR on my iPhone widget."

What you need

1. The free WidgetDash iOS app: https://apps.apple.com/us/app/widgetdash/id6761054679, with a WidgetDash widget on your Home Screen or Lock Screen.
2. Your API keys. Get them at https://widgetdash.app/app.
   • Write key: lets the agent create and update your widget data.
   • Read key (optional): read-only access. If you leave it out, the read tools use the write key.
3. Node.js 18 or newer (npx comes with it).

Setup

Claude Code

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

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

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

Cursor

Add this to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

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

Other MCP clients that can launch a stdio server work the same way. The command is npx -y widgetdash-mcp, and the keys go in the environment variables below.

Environment variables

Variable	Required	Description
WIDGETDASH_WRITE_KEY	For writes	Write key from https://widgetdash.app/app. push_metrics, push_number and delete_source need it.
WIDGETDASH_READ_KEY	No	Read key. list_sources and get_widget_data use it, or the write key if it isn't set.
WIDGETDASH_API_URL	No	API base URL. Default: https://api.widgetdash.app.

Example prompts

• "Put my Stripe MRR on my iPhone widget." (The agent reads the number with a Stripe tool, then calls push_number.)
• "Show today's GitHub stars, open issues and open PRs for my repo on my Lock Screen widget."
• "Make a 'Server' widget with CPU as a progress bar, uptime as a number and a green 'Healthy' status badge."
• "Every time you finish a build, set the 'CI' widget status to Passing or Failing."
• "What's on my WidgetDash widget right now?"
• "Remove the old 'test' source from my widget."

Tools

Tool	What it does
push_number	Sets one value on a source, e.g. MRR = $12,400. Other metrics on the source stay as they are. The metric is matched by label. If the source doesn't exist yet, it is created.
push_metrics	Creates or updates a source: title (display_name), SF Symbol icon, category, sort_order (new sources only; reorder in the app) and the full metrics list. The list replaces the source's current metrics.
list_sources	Lists your sources (key, title, icon, hidden or shown) and how many your plan allows. The free plan allows 5.
get_widget_data	Shows what's on the widget now: every enabled source with its metrics and last update time, or a single source.
delete_source	Permanently deletes a source and ends any Live Activity for it.

Metrics

Each metric has a label, a value, an optional type, an optional color and an optional wide:

• type sets how the widget draws the value:

  • number: a big bold figure.
  • text: a plain string.
  • status: a colored badge.
  • progress: a bar. The value must be 0 to 100, and a trailing % is removed for you.
  • percentage: compact percent text.
  • timestamp: a moment, shown as a live relative time such as "8 hours ago". Send an ISO 8601 time (2026-10-23T05:00:00Z) or Unix epoch seconds. Reads show the relative time plus the exact time.

  If you leave type out, values that look like numbers (42, $12,400, 3.5%) become number and everything else becomes text. With push_number, an existing metric keeps its current type, color and wide, and the source's other metrics are re-sent as they were stored: timestamps keep their exact time, and colors chosen by the source's color rules stay under the rules' control.

• color: green, red, yellow, blue, gray, orange, purple or cyan.

• wide: true gives the metric a full-width row of its own on Large widgets (iOS app 1.8 or later), for long text such as a title. Other text that shares a row shows up to two lines. Put wide metrics last to keep the others in one row.

• icon: any SF Symbol name, e.g. dollarsign.circle.fill, chart.bar.fill, server.rack or heart.fill.

Fields you leave out (display_name, icon, category, raw_data) keep their current values. sort_order only places a new source: once it exists, its order is the one set in the app, so an agent can't undo it.

Security

• The write key can only write your own widget data. It can't reach other users' data or your account's billing.
• Keys go only in the Authorization header of requests to the WidgetDash API. The server never logs them and removes them from any error text it returns.
• Treat the write key like a password. If it leaks, rotate it at https://widgetdash.app/app.
• The server only talks to WIDGETDASH_API_URL, which is https://api.widgetdash.app by default.

Development

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

npm test runs every tool through a real MCP client over stdio, against an in-memory mock of the WidgetDash API (test/mock-api.mjs). It needs no network and no keys, and it never contacts production.

To try it interactively, run npx @modelcontextprotocol/inspector node dist/index.js.

MCP Registry

server.json is the entry for the official MCP Registry under the name io.github.purian/widgetdash-mcp, following schema 2025-12-11. The mcpName field in package.json must match that name for npm ownership verification. Status: draft. It hasn't been published yet, and the registry is still in preview, so check server.json against the current schema before running mcp-publisher publish.

License

MIT © WidgetDash