Push Notifications From Gemini CLI

Gemini CLI is good at the long jobs. Point it at a repository, ask it to work through a migration, and it will grind through file after file while you do something else. Which is the problem: you are doing something else, and the terminal has no way to reach you.

The fix is a notification tool the agent can call itself. Gemini CLI speaks MCP, and MCP is how you hand an agent a capability it did not ship with. Five minutes, one config block.

Why MCP rather than a shell command

You could tell Gemini to run curl at the end of a task. It would work, right up until the run where it decides not to, or quotes the JSON wrong, or the shell tool is not enabled.

Registering a tool is different. The model sees a typed capability with a name and a description, it knows what arguments to pass, and calling it is a normal part of finishing a job rather than an improvised shell invocation. It also means no API key in your config file, which is the part that matters most.

Step 1: Find your settings file

Gemini CLI reads MCP servers from settings.json. There are two useful locations:

• ~/.gemini/settings.json for every project
• .gemini/settings.json inside a repo, for that repo only

Use the global file. A notification tool is not project-specific, and you want it available on whatever you happen to be running tonight.

Step 2: Add the server

{
  "mcpServers": {
    "notifications": {
      "httpUrl": "https://thenotification.app/api/mcp"
    }
  }
}

That is the whole configuration. The server is remote and streams over HTTP, so there is no command to run, no package to install, and no local process to keep alive. If you already have other MCP servers configured, add this as another key alongside them and leave the rest untouched.

Step 3: Sign in with Apple

Start Gemini CLI. On first use of the server you will be asked to authorise it, which happens through Sign in with Apple rather than an API key.

This is worth a sentence, because it is the difference between this and most MCP setups. There is no key to generate, paste, commit by accident, or rotate later. Your CLI holds a short-lived token tied to your Apple ID, and nothing long-lived sits in settings.json. The reasoning is in why Sign in with Apple beats API keys for MCP connectors.

One requirement: install the iOS app and sign in with the same Apple ID first. The push needs a registered device to land on. No app, no buzz, and the tool call will look like it worked.

Step 4: Ask for the ping

Once connected, Gemini lists the server's tools and can call them. Say so explicitly at the end of your prompt:

Work through every file in src/legacy and convert the callbacks to
async/await. Run the tests when you are done. Then send me a notification
with how many files you changed and whether the tests passed.

Gemini treats the notification as the last step of the job: finish the work, then call the tool with a title and body it writes itself. Because it composes the message, the notification says "38 files converted, 2 tests failing" rather than "task complete", which is the difference between an alert you act on and one you have to investigate.

The tool takes the same fields as the REST API: title and body are required, link and image are optional. Ask for a link to the PR or the CI run and the notification becomes tappable.

Being specific about when to fire

Left to its own judgement, a model's idea of "notify-worthy" drifts. Put the rule in the prompt, or in a GEMINI.md so it applies to every session in the repo:

# Notifications

Send a push notification when:
- a task that took more than two minutes finishes
- you hit something ambiguous and need a decision before continuing
- the test suite goes from green to red

Do not notify on progress updates or individual file edits.

That last line is the one that keeps this useful. A tool the agent can call is a tool it will call, and an agent that pings you per file is one you mute within a day.

When nothing arrives

• The server is not listed. Check the CLI actually loaded it, and that the JSON is valid. A trailing comma in settings.json silently drops the whole file.
• No device registered. The app has to be installed and signed in with the same Apple ID as the connector.
• The model just did not call it. Say it more directly in the prompt. "Send me a notification when you are done" beats "let me know."
• You are out of quota. The API returns a 429 with your limit rather than failing quietly, so check the tool output.

The honest part

The free tier is 100 notifications for the lifetime of the account, not per month. One ping per long task means that lasts a while. Wire it to a chatty agent with no rules and it will not. Pro is $2.99 a month for 1,000.

And this delivers to iPhone only. It rides Apple's push service, so an Android phone is out of scope here.

Same server, other clients

The connector is not Gemini-specific. The same URL works in Claude, Cursor and anything else that speaks MCP, so setting it up once covers whichever tool you are in this week. There is a client-agnostic walkthrough in adding a notification tool to any MCP agent, and the underlying HTTP call is in the API reference if you would rather skip MCP entirely.

Add the four lines, kick off the long job, and go do something else properly.

New to this? Start with what an MCP server is.