Skip to main content
Glama
grzgrzgrz3

pingwa

by grzgrzgrz3
OverviewSchemaRelated ServersScoreDiscussions
Python

pingwa (client)

PyPI Python License: MIT

WhatsApp notifications for AI agents and scripts with zero setup — no Meta account, no templates, no dashboard: text "join", get an API key, curl → WhatsApp in 60s. Two-way human-in-the-loop: your agent asks, you tap a button to answer. From your terminal or an MCP client.

This is the open-source (MIT) pingwa client: a CLI, a tiny HTTP client, and an MCP server. It talks to a pingwa backend (the hosted service at https://pingwa.dev, or your own). The backend is separate and private; this client is not.

Install & use

No install needed with uv:

export PINGWA_KEY=pw_your_key          # get one: send "join" on WhatsApp to the service number
uvx pingwa send "build finished ✅"     # notify your own phone
echo "deploy done" | uvx pingwa send -  # from stdin
uvx pingwa ask "Deploy to prod?" --button yes --button no   # wait for a reply from your phone
uvx pingwa replies                      # pull messages your phone sent back (out-of-band steering)
uvx pingwa me                           # plan / quota / reply-window
uvx pingwa keys                         # list active API keys (up to 10 named keys per number)
uvx pingwa keys revoke ci               # revoke one by name (or reply 'revoke ci' on WhatsApp)
uvx pingwa upgrade                      # get a Stripe link to go Pro (no password needed)
uvx pingwa send "x" --json              # raw JSON response

AI agents: don't ask your human to copy-paste a key — drive the registration yourself (POST /v1/registrations; full recipe in llms.txt). The human only taps one WhatsApp link; the key is claimed by you and never travels through the chat. Works for existing accounts too — it mints an additional named key.

Exit codes: 0 ok · 2 missing key · 3 quota exceeded · 1 other. Override the backend with PINGWA_BASE_URL or --base-url.

Related MCP server: whatsapp-mcp-server

Webhooks

Prefer PUSH over polling replies? Register HTTPS endpoints and pingwa POSTs every inbound WhatsApp message to them:

uvx pingwa webhooks                                   # list your webhooks
uvx pingwa webhooks add https://your-host/pingwa-hook # returns a signing SECRET, shown ONCE
uvx pingwa webhooks rm https://your-host/pingwa-hook  # by id, or by exact url

add prints a whsec_... secret once — store it now; it never appears again. Each delivery carries an X-Pingwa-Signature: sha256=<hex> header (an HMAC-SHA256 of the raw body under that secret) — verify it and reject anything that fails. Full verification recipe and payload shape: llms.txt. Up to 5 active webhooks per account; to rotate a secret, rm then add again.

MCP server

Same tools on stdio and remote: notify(text), ask(text, buttons?, timeout?), check_replies(since?, wait?), check_status(), upgrade().

Local (stdio) — for Claude Desktop / Claude Code:

{
  "mcpServers": {
    "pingwa": {
      "command": "uvx",
      "args": ["pingwa", "mcp"],
      "env": { "PINGWA_KEY": "pw_your_key" }
    }
  }
}

Remote (Streamable HTTP, no install):

{
  "mcpServers": {
    "pingwa": {
      "url": "https://pingwa.dev/mcp",
      "headers": { "Authorization": "Bearer pw_your_key" }
    }
  }
}

Every error carries an action hint, so an agent knows what to do next.

What it sends

Only your message text and your key, to the pingwa backend you point it at — over HTTPS. Nothing else. The recipient is always your own phone (there is no "to" field). See the service's /privacy.

License

MIT — see LICENSE in the repository root. It covers this client package only (src/pingwa/client/); the pingwa server is separate, private, and not published. See NOTICE for the exact boundary.

Available Tools

3 tools
check_statusBInspect

Show the pingwa account's plan, remaining monthly quota, and whether the free 24h WhatsApp reply window is currently open.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not mention that the tool is read-only, safe, or non-destructive. The user must infer from 'Show' that it is a query, but this is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is concise and front-loaded. Every word adds value: it specifies the account, the three key pieces of information, and the WhatsApp window status. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has zero parameters and an output schema is present, the description is complete. It lists exactly what the tool returns, which matches the output schema expectations. No additional context is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed as the schema coverage is 100% (empty properties).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows account plan, monthly quota, and WhatsApp reply window status. It uses a specific verb 'show' and identifies the resource (pingwa account). Sibling tools are different actions, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It could be used to check account status before taking other actions, but the description does not provide this context or any usage conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notifyAInspect

Send a WhatsApp notification to the account owner's own phone.

text is the message (1-1024 chars). image_url (optional) is a public https image link — a screenshot, chart or diff — delivered as an image with text as the caption when the user's 24h window is open (otherwise text only). Returns a confirmation with the queued message id; raises an actionable error on quota/auth.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes
image_urlNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explains image delivery behavior (caption vs text only based on 24h window), error handling (quota/auth), and return value (confirmation with message id). Some details like rate limits are omitted, but it is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with 5-6 sentences, front-loaded with the main purpose, then parameter details and behavior. No fluff or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no annotations, output schema present), the description covers purpose, parameters, behavior, errors, and return value. It is complete for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains text constraint (1-1024 chars) and image_url behavior (public https link, delivered as image with caption when window open). This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends a WhatsApp notification to the account owner's own phone, distinguishing it from siblings check_status and upgrade. It specifies the verb 'send' and the resource 'WhatsApp notification'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for sending notifications but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Given the distinct sibling tools, the purpose is clear but no direct usage advice is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

upgradeAInspect

Get a link to upgrade the account to Pro (raises the monthly quota).

Returns a Stripe Checkout URL for the human to open and pay — no pingwa password needed, the card is handled by Stripe. If the account is already Pro, returns a billing-portal URL to manage or cancel instead.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully describes behavior: returns Stripe Checkout URL for human payment, no password needed, and returns billing-portal for existing Pro accounts. It discloses the side effect of raising quota and the interactive nature of the process.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each serving a purpose: first states overall goal, second explains the Stripe URL usage, third adds the alternative case for existing Pro accounts. Very concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description covers all necessary context: what the tool does, what it returns, and edge-case behavior. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so schema coverage is 100%. The description does not need to add parameter information. Baseline for 0 parameters is 4, and the description is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a URL to upgrade the account to Pro, with specific handling for already Pro accounts (billing-portal URL). The verb 'upgrade' and resource 'account to Pro' are precise, and the two cases are well delineated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for upgrading accounts, but lacks explicit guidance on when to use this tool versus alternatives. Siblings are notify and check_status, which are unrelated, so no comparative context is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool serves a distinct purpose: notify sends a notification, check_status shows account status, and upgrade provides a link to upgrade. There is no overlap or ambiguity.

Naming Consistency4/5

Tool names use verbs consistently (notify, check_status, upgrade), though check_status is a verb_noun while the others are single verbs. This minor deviation does not hinder clarity.

Tool Count5/5

With three tools, the server is well-scoped for a personal notification service. Each tool is essential and neither too few nor too many for the purpose.

Completeness4/5

The tool set covers the core workflows: sending notifications, checking status, and upgrading. Missing features like notification history or contact management are minor gaps for this simple self-notification domain.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • whatsapp-mcp-server

    FredShred7
    A
    license
    A
    quality
    D
    maintenance
    Connects AI assistants to the official Meta WhatsApp Cloud API for managing conversations and sending various message types through natural language. It provides tools for media management, template messages, and real-time webhook processing without the risk of account bans.
    18
    47
    23
    MIT

  • wa-bridge

    xbirimensah
    A
    license
    Not graded
    quality
    A
    maintenance
    A self-hosted WhatsApp bridge that exposes a stdio MCP server with ~20 tools for reading conversations, sending messages, managing groups, contacts, and aliases, enabling AI agents to operate WhatsApp directly.
    2
    MIT

  • whatsapp

    bowlofarugula
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for sending and reading WhatsApp messages through Claude, with human approval on sends and no auto-replies.
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/grzgrzgrz3/pingwa-client'

If you have feedback or need assistance with the MCP directory API, please join our Discord server