docs

Query your data with Claude

Your heliumOS data is available to Claude through the heliumOS data MCP, a read-only SQL connection to your operator's live data. Ask a question in plain English ("how many lines are on family plans?", "what did plan revenue do last month?") and Claude writes and runs the query, under your own heliumOS account.

Who can use it

Anyone on your team whose role includes data access. By default that is Owner and Admin, the two roles that already read subscriber PII without the CPNI step-up.

SQL reads the underlying tables directly, so the dashboard's PII redaction and the per-subscriber CPNI step-up do not apply. Data access is a bulk-export privilege for people already trusted with PII outright, and your heliumOS contact can only grant it to a role that holds unconditional PII access.

Connect

Claude (claude.ai and Claude Desktop)

  1. Open Settings → Connectors → Add custom connector.
  2. URL: https://data.os.helium.com/mcp
  3. Save, then Connect. Claude sends you to os.helium.com to sign in with your usual heliumOS login.

Claude Code

claude mcp add --transport http heliumos-data https://data.os.helium.com/mcp

Then run /mcp in Claude Code, pick heliumos-data, and choose Authenticate. Any HTTPS callback or a callback on a loopback address (127.0.0.1, [::1], or localhost) is accepted. A client cannot register a claude.ai or loopback callback alongside one on any other host.

What it can see

  • Your live data only. Every query is pinned to your operator and your live environment by the database itself. Sandbox data and other operators' data are not reachable.
  • Tenant tables, read-only. Subscribers, subscriptions and lines, SIMs, ports, plans and add-ons, invoices and payments, promotions and referrals, usage. Credentials, API keys, webhook secrets and CPNI one-time codes are not readable at all.
  • No writes. Anything other than a read is refused before it runs.

What Claude is told

The connection carries a data guide: how the tables fit together and the one correct query for each headline figure, the same definitions the heliumOS dashboard uses. Claude reads it before its first query. Two things it covers that are easy to get wrong without it:

  • Family plans. One subscription, several people. A SIM's subscriber_id is the payer; the person holding the phone is found through the SIM's line. Several SIMs under one subscriber is normal.
  • Which "active". Active subscribers (people), active lines, accounts in service, and billable lines are four different numbers. Ask for the one you mean, and Claude will say which definition it used.

If an answer looks off, ask Claude which guide definition it used.

Limits

  • One statement per call. A LIMIT 1000 is added when a query has none, and a result stops at 10,000 rows. Aggregate in SQL rather than pulling rows.
  • Figures for the most recent day are still arriving: usage for a closed day keeps growing for about two days.
  • Queries run on the production database. Prefer bounded time ranges on large tables such as usage_records and events.

Your account, your record

Every statement, including ones that are refused, is recorded against your heliumOS account with the full SQL and time. Access follows your team membership: if you leave the team or your role loses data access, new tokens stop within the hour.

Example questions

  • How many active subscribers, active lines, and accounts do we have right now?
  • How many lines are on family plans, and what's the most common plan size?
  • What were billable lines for last month?
  • Plan revenue by plan for the last three months.
  • How many ports in are still in progress, and how old is the oldest?
  • Carrier data per line last cycle, top 20.