How to add product analytics to your app with Gemini CLI

Gemini CLI is Google's AI agent for the terminal. It can add product analytics to your app in one session, as long as it reads current Amplitude docs and your real event names instead of guessing.

In this tutorial, you'll connect Gemini CLI to Amplitude, add your API key, have Gemini install the SDK, review its changes, and save the rules in GEMINI.md.

What you'll build

Prerequisites

• Gemini CLI installed and signed in with a Gemini Code Assist Standard or Enterprise license or a paid Gemini API key. Since June 18, 2026, Gemini CLI no longer serves requests for free, Google AI Pro, or Google AI Ultra accounts.
• A web or Node.js project in a Git repository, so you can review and revert Gemini's changes with git diff.
• A browser on the same machine as Gemini CLI. Amplitude's sign-in uses OAuth, and Gemini CLI catches the redirect on localhost, so it doesn't work from a remote SSH session or a container without a browser.
• An Amplitude account with access to a project, and that project's API key. In Amplitude, go to Settings > Projects > your project > General.

No Amplitude account yet? A free account is enough for this tutorial; nothing here needs a paid Amplitude plan. Sign up for free to get your project API key.

1. Connect Gemini CLI to Amplitude

Add two MCP servers from your terminal. The first is the authenticated Amplitude MCP server, which reads your projects and tracking plan with your own Amplitude permissions. The second is the public Docs MCP server, which serves current Amplitude documentation and needs no sign-in. The Gemini CLI setup guide and the Docs MCP server page list both URLs.

gemini mcp add --transport http --scope user amplitude https://mcp.amplitude.com/mcp
gemini mcp add --transport http --scope user amplitude-docs https://amplitude.com/docs/api/mcp

--scope user writes both servers to ~/.gemini/settings.json, so they're available in every project. Without it, gemini mcp add defaults to project scope and writes to .gemini/settings.json in the current folder only. If your Amplitude data lives in the EU region, use https://mcp.eu.amplitude.com/mcp in the first command.

If you'd rather edit ~/.gemini/settings.json by hand, add this:

{
  "mcpServers": {
    "amplitude": {
      "httpUrl": "https://mcp.amplitude.com/mcp"
    },
    "amplitude-docs": {
      "httpUrl": "https://amplitude.com/docs/api/mcp"
    }
  }
}

Start Gemini CLI at your repository root. If it asks whether to trust the folder, choose Trust folder; in an untrusted folder Gemini CLI doesn't connect to MCP servers at all. Then sign in to Amplitude and check both servers:

gemini
/mcp auth amplitude
/mcp list

/mcp auth amplitude opens your browser for the Amplitude OAuth flow. /mcp list should show amplitude and amplitude-docs as connected. Then ask Gemini:

What Amplitude projects can I access?

A list of your projects means the Amplitude MCP server is connected and authenticated. Gemini CLI asks before it runs each MCP tool. For amplitude-docs, which is read-only, choosing to always allow the server saves you a lot of prompts. Keep approving amplitude calls one at a time, since some of them write to your tracking plan.

2. Add your API key to the env file

Add the key yourself, before you run the install prompt, rather than pasting it into the chat. For a Vite app, add this line to .env.local at the project root:

VITE_AMPLITUDE_API_KEY=your-project-api-key

In Next.js, the browser variable is NEXT_PUBLIC_AMPLITUDE_API_KEY instead. A Node.js server can read a plain AMPLITUDE_API_KEY.

3. Run the install prompt

Paste this prompt into Gemini CLI. It points Gemini at the Quickstart through the Docs server instead of its memory, and pins the decisions agents most often get wrong.

Install Amplitude analytics in this project.

Before writing code:
1. Use the amplitude-docs MCP server. Call get_page on
   "get-started/amplitude-quickstart" and use the install path it
   recommends for this project's stack. Do not pick a package from memory.
2. Use the amplitude MCP server. Call get_amplitude_context, list my
   projects, and ask me which project this app should send to.
3. Show me your plan and wait for my approval before editing files.

Then:
- Read the API key from the environment variable I already added to my
  env file: VITE_AMPLITUDE_API_KEY for a Vite app,
  NEXT_PUBLIC_AMPLITUDE_API_KEY for Next.js, AMPLITUDE_API_KEY for a
  Node.js server. Don't create another env file, and never hardcode the key.
- Initialize the SDK exactly once, at app or process startup, outside any
  render path or request handler. If pages render on the server, guard the
  browser init with typeof window !== "undefined".
- In browser code, rely on autocapture for page views. Do not add manual
  page view tracking.
- If the app has a login flow, call setUserId with the signed-in user's ID
  after login and reset() on logout.
- User IDs must be strings of 5 or more characters. If our IDs are integers,
  prefix them, for example "user-" + id, and use the same format on client
  and server.
- In server code, pass user_id or device_id on every track call, and await
  flush().promise before the process exits or a serverless handler returns.
- If the package you install turns on session replay, tell me, and show me
  how to turn it off.
- Do not add any custom events yet.

When you finish, list every file you changed and why.

Gemini comes back with the docs page it read, a project question, and a plan. Pick the project, approve the plan, and approve the file edits and the install command as Gemini asks for them.

4. Review what Gemini CLI changed

Run git diff before you start the app. You can do it without leaving the session: type !git diff in Gemini CLI to run it as a shell command. These are the mistakes that show up most often, and each takes seconds to spot:

1. Package. For browser apps installed from npm, the Quickstart recommends @amplitude/unified. For Node.js servers, it's @amplitude/analytics-node. Anything else deserves a question.
2. API key. Search the diff for the literal key. It should appear only in your env file, never in source.
3. Env file. The code reads the variable you added in step 2, and Gemini didn't create a second env file with a different name.
4. Init location. One initAll or init call, in a module that runs once. Not inside a React useEffect, a component body, or an Express route.
5. Duplicate page views. No hand-written track("Page Viewed") next to autocapture, which tracks page views by default.
6. Server flushing. Every server-side track path ends with await flush().promise before shutdown or before a serverless handler returns.
7. Session replay. @amplitude/unified records sessions when sessionReplay.sampleRate is above 0. Keep it, or set it to 0 on purpose.

For a Vite browser app, a correct result looks like this. In Next.js, the variable is process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY instead, and the call sits behind a typeof window !== "undefined" check, because Next.js also renders on the server.

import { initAll } from "@amplitude/unified";

initAll(import.meta.env.VITE_AMPLITUDE_API_KEY, {
  sessionReplay: {
    sampleRate: 1, // set to 0 to turn session replay off
  },
});

If something fails the review, ask Gemini to fix it in the same session:

Move the Amplitude init out of the component into src/lib/amplitude.ts so
it runs once at startup, and read the key from
import.meta.env.VITE_AMPLITUDE_API_KEY instead of the literal string.
Show me the diff.

5. Add an event that matches your taxonomy

This is where the Amplitude MCP server earns its setup. Ask Gemini to check what already exists, in the code and in Amplitude, before it names anything.

I want to track when a user exports a report, with the file format as a
property.

1. Find how analytics is already implemented in this repo: import paths,
   helper functions, and event naming style.
2. Use the amplitude MCP server's get_amp_taxonomy tool to list the
   existing events and event properties in the project we picked.
3. If an event for this already exists, use its exact name and property
   names. If not, propose a name that matches the casing of the existing
   events, and wait for me to confirm it.
4. Add one track call where the export actually happens, after it
   succeeds, not in an effect or a render.

If your tracking plan uses Title Case with spaces, Gemini should propose Report Exported, not reportExported or report_exported. Once you confirm, it adds a single call in the export handler:

import { track } from "@amplitude/unified";

track("Report Exported", { format });

Verify it worked

Run the app the way you normally do, load a page, export a report, then check in this order:

1. Network tab or process logs. In the browser, filter the Network tab for api2.amplitude.com and look for a POST to /2/httpapi returning 200. On a server, set the SDK's logLevel to Debug and watch the upload in the terminal.
2. Ingestion Debugger. In Amplitude, click Data, select Sources, then open the Ingestion Debugger tab. The successful requests and the events and identify counts charts should show your uploads.
3. User Profiles. Go to Users > User Profiles and search your user ID or device ID. [Amplitude] Page Viewed and Report Exported appear in the event stream within ten seconds to a minute. Click Report Exported to confirm the format value.
4. Ask Gemini. With the Amplitude MCP server connected, ask it to check the data for you:

Using the amplitude MCP server, look up my user profile in this project
and tell me whether "Report Exported" arrived in the last hour and which
format values it has.

Troubleshooting

/mcp list shows amplitude-docs as disconnected

The Docs server only speaks Streamable HTTP, so check its entry in ~/.gemini/settings.json. It needs either httpUrl, or url with "type": "http". An entry set to SSE ("type": "sse", or an --transport sse add) can't connect. Fix the entry, or remove it with gemini mcp remove --scope user amplitude-docs and add it again with --transport http.

Gemini says it has no Amplitude tools

Either the folder isn't trusted, so Gemini CLI skips every MCP server, or you added the servers without --scope user from a different folder. Run /permissions to trust the current folder, and run gemini mcp list in your terminal to see which servers are configured and connected.

/mcp auth amplitude never completes

The OAuth flow needs a local browser and a redirect to localhost, so it fails over SSH or in a container. Run Gemini CLI on a machine with a browser. If the authorization page spins, close the tab after you approve access, and make sure you're signed in to only one Amplitude organization during the flow. Then run /mcp auth amplitude again.

Gemini installed a different package than the Quickstart names

It skipped the docs lookup. Ask it to call get_page on get-started/amplitude-quickstart through amplitude-docs and redo the install from that page.

Events show in the Network tab but not in the project

The key belongs to a different project than the one you picked, or it's an EU project sending to the US endpoint. Compare the key in your env file with Settings > Projects > your project > General, and set serverZone: "EU" in initAll for EU projects.

User Profiles shows events with no user ID

The ID is shorter than 5 characters, so Amplitude dropped it. Integer database IDs like 42 fail this. Prefix them, for example user-42, and use the same format on the server.

The MCP server returns a permission error on taxonomy writes

Your role lacks Use MCP (write) or the Update Tracking Plan permission in Amplitude Data, or your org admin restricted MCP access under Settings > Content Access > MCP. If only write access is missing, reads still work. Ask an admin for write access, or make the tracking-plan change in the Amplitude UI.

Save the rules in GEMINI.md

Gemini CLI loads GEMINI.md files into every prompt: a global one at ~/.gemini/GEMINI.md, then any it finds from your working directory up to the repository root, plus any in a subdirectory once Gemini reads files there. Put the conventions from this page in a GEMINI.md at the repository root, so the next time you ask Gemini to track something it follows them without the long prompt. Commit it, so your teammates' sessions follow the same rules.

## Analytics (Amplitude)

- Look up Amplitude SDK usage with the amplitude-docs MCP server before
  writing analytics code. Never install or import Amplitude packages from
  memory.
- Before adding a track call, list existing events with the amplitude MCP
  server (get_amp_taxonomy) and reuse existing event and property names.
  Match the existing casing. Ask before creating a new event name.
- The SDK is initialized once in src/lib/amplitude.ts. Never call init or
  initAll anywhere else.
- The browser API key is VITE_AMPLITUDE_API_KEY in .env.local. Never
  hardcode it and never create another env file for it.
- Page views come from autocapture. Never add manual page view tracking.
- User IDs are "user-" + the database ID, the same on client and server.
  Call setUserId after login and reset() on logout.
- Server code passes user_id or device_id on every track call and awaits
  flush().promise before exit or before a serverless handler returns.
- Track user actions in event handlers after the action succeeds, not in
  effects or render paths.
- Ask before creating tracking-plan events.

Change src/lib/amplitude.ts and the variable name to whatever Gemini created in step 3. Start a new Gemini CLI session, then run /memory show to confirm the rules are loaded. /memory list shows which GEMINI.md files are in use.

If your team already keeps agent rules in AGENTS.md, you don't need a second copy. Set context.fileName in .gemini/settings.json to ["AGENTS.md", "GEMINI.md"] and Gemini CLI reads both.

What this unlocks

• Session replay, if you kept sampleRate above 0, lets you watch the session where Report Exported fired, or the one where someone opened the export menu and gave up.
• Heatmaps, built from those same session replays, show where people clicked on the reports page before they exported.
• Feature Experiment can test a new export flow with Report Exported as the success metric, and Gemini can create the flag through the Amplitude MCP server with create_flags.
• Guides and surveys can point people who view reports but never fire Report Exported at the export button.

One integration; everything else reads from the same events.

Next steps

Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.