Back to Browse

Widgetdash MCP Server

by Purian
Developer ToolsModerate5.6MCP RegistryLocal
Free

Server data from the Official MCP Registry

Push any number to your iPhone Home Screen / Lock Screen widgets and Live Activities.

About

Push any number to your iPhone Home Screen / Lock Screen widgets and Live Activities.

Security Report

5.6
Moderate5.6Moderate Risk

WidgetDash MCP server is a well-structured stdio server that pushes metrics to iPhone widgets via the WidgetDash REST API, authenticated with a write/read key sent only in the Authorization header. No malicious patterns, shell execution, or hardcoded secrets were found; permissions (network_http, env_vars) match its stated purpose. Minor notes concern unrestricted metric and value sizes beyond sanity caps and the unconditional default API URL override, both low severity. Supply chain analysis found 6 known vulnerabilities in dependencies (0 critical, 4 high severity). Package verification found 1 issue.

6 files analyzed · 9 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

WidgetDash write key (from https://widgetdash.app/app). Required to push or delete widget data.Required

Environment variable: WIDGETDASH_WRITE_KEY

Optional WidgetDash read key for read-only tools. Falls back to the write key.Required

Environment variable: WIDGETDASH_READ_KEY

API base URL.Optional

Environment variable: WIDGETDASH_API_URL

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "widgetdash-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "widgetdash-mcp@0.2.0"
      ],
      "env": {
        "WIDGETDASH_API_URL": "your-widgetdash-api-url-here",
        "WIDGETDASH_READ_KEY": "your-widgetdash-read-key-here",
        "WIDGETDASH_WRITE_KEY": "your-widgetdash-write-key-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

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

VariableRequiredDescription
WIDGETDASH_WRITE_KEYFor writesWrite key from https://widgetdash.app/app. push_metrics, push_number and delete_source need it.
WIDGETDASH_READ_KEYNoRead key. list_sources and get_widget_data use it, or the write key if it isn't set.
WIDGETDASH_API_URLNoAPI 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

ToolWhat it does
push_numberSets 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_metricsCreates 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_sourcesLists your sources (key, title, icon, hidden or shown) and how many your plan allows. The free plan allows 5.
get_widget_dataShows what's on the widget now: every enabled source with its metrics and last update time, or a single source.
delete_sourcePermanently 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

Reviews

No reviews yet

Be the first to review this server!