Skip to content

// ai agents and mcp

Via API

Gemini CLI email verification with pingutil

Gemini CLI can sort and rewrite a contacts file in seconds, but it cannot know whether an address bounces. An mcpServers entry with httpUrl pointing at pingutil gives it the verification and classification tools, and settings.json expands $PINGUTIL_API_KEY so the key stays in your environment.

Where it connects: Gemini CLI settings.json mcpServers entry with httpUrl (Streamable HTTP) and headers

What goes wrong without it

  • Gemini rewrote our mailing list file and every typo survived.
  • I run agents in scripts and need the config to work without anyone typing a key.
  • I keep asking the model whether a domain is a real company and it just makes something up.

What you can do with Gemini CLI and pingutil

  • Verify a list from the terminal

    Ask Gemini CLI to verify the addresses in a text file with verify_emails, in groups of 50, and print a summary of valid, invalid, risky and unknown with reasons.

  • Classify domains for a report

    Give it a list of signup domains and ask for a category per domain from lookup_email with fast: true, so the report separates company, free webmail and disposable signups.

  • Answer "who is this company" from data

    For a single domain, lookup_email returns a company profile with confidence, so the answer comes from pingutil's lookup rather than the model's memory.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and export it as PINGUTIL_API_KEY.

  2. 2

    Open ~/.gemini/settings.json for all projects (or .gemini/settings.json in one project) and add a pingutil entry under mcpServers.

  3. 3

    Set httpUrl to https://pingutil.com/mcp and an Authorization header of Bearer $PINGUTIL_API_KEY; Gemini CLI expands environment variables in settings.json string values.

  4. 4

    Leave trust at false so Gemini asks before each tool call, or set it to true once you are comfortable with the calls it makes.

  5. 5

    Start gemini, run /mcp to see the pingutil tools, and ask for a check.

~/.gemini/settings.json
{
  "mcpServers": {
    "pingutil": {
      "httpUrl": "https://pingutil.com/mcp",
      "headers": {
        "Authorization": "Bearer $PINGUTIL_API_KEY"
      },
      "timeout": 120000,
      "trust": false
    }
  }
}

What to do with each result

pingutil resultAction in Gemini CLI
status validCount the address as deliverable in the summary.
status invalid with did_you_meanPrint the suggested fix next to the address.
status risky or unknownList separately as unconfirmed, not as bad.
lookup_email: category disposableCount as a throwaway signup in the domain report.
company.confidence lowReport the company match as uncertain instead of stating it as fact.

Limits to plan for

  • Gemini CLI's default request timeout is 600,000 ms; the example lowers it to 120 s so a stuck batch fails sooner. Mailbox checks on slow mail servers can take up to about 25 s each.
  • gemini mcp add --transport http with --header also works, but the shell expands $PINGUTIL_API_KEY before Gemini saves it, so the key ends up in settings.json (project scope by default). Editing the file keeps the variable reference instead.
  • Calls count toward the key's Free plan limits: 300 verifications a day and 3,000 a month, 2,000 lookups a day and 30,000 a month, 50 new company profiles a day and 500 a month. No OAuth.

Gemini CLI documentation

Gemini CLI is a trademark of its owner. This integration uses Gemini CLI's documented extension points; it is not an official Gemini CLI app.

Common questions

httpUrl or url?
httpUrl. In Gemini CLI, httpUrl is the Streamable HTTP endpoint, which is what pingutil serves. pingutil does not offer an SSE stream.
Does Gemini see my API key?
Gemini CLI adds the header to its requests; the model gets tool results. Keep the key in the environment, not in a project settings file that is committed.
Which tools does the server expose?
verify_email, verify_emails (up to 50 addresses) and lookup_email, all read-only.

Stop bad addresses in Gemini CLI today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Gemini CLI setup will receive.