--- title: "How to add product analytics to your app with Gemini CLI" description: "Connect Gemini CLI to Amplitude's MCP servers over Streamable HTTP, have it install the right SDK, review its changes, and save the rules in GEMINI.md." canonical: "https://amplitude.com/en-us/build/gemini-cli-product-analytics" --- # How to add product analytics to your app with Gemini CLI Connect Gemini CLI to Amplitude's MCP servers over Streamable HTTP, have it install the right SDK, review its changes, and save the rules in GEMINI.md. Source: https://amplitude.com/en-us/build/gemini-cli-product-analytics --- # How to add product analytics to your app with Gemini CLI Connect Gemini CLI to Amplitude's MCP servers, hand it one prompt that installs the SDK the docs recommend for your stack, review its changes for the mistakes agents make, and save the rules in GEMINI.md. About 15 minutes, all copy-paste. - Gemini CLI - Amplitude MCP - Docs MCP - GEMINI.md - 15 min Chris Tam · Last updated 6 October 2026 Gemini CLI is Google's AI agent for the terminal. It can add [product analytics](https://amplitude.com/amplitude-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](https://amplitude.com/mcp), add your API key, have Gemini install the SDK, review its changes, and save the rules in GEMINI.md. ## What you'll build A Gemini CLI setup connected to the Amplitude MCP server and the Docs MCP server, an app instrumented with the SDK the Quickstart recommends for its stack, one `Report Exported` event named to match your existing taxonomy, and a `GEMINI.md` that keeps Gemini on those conventions. By the end you'll see live events in your Amplitude project. ## 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](https://app.amplitude.com/signup) 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](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/gemini-cli) and the [Docs MCP server page](https://amplitude.com/docs/amplitude-ai/docs-mcp-server) list both URLs. Terminal ```sh 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: \~/.gemini/settings.json ```json { "mcpServers": { "amplitude": { "httpUrl": "https://mcp.amplitude.com/mcp" }, "amplitude-docs": { "httpUrl": "https://amplitude.com/docs/api/mcp" } ``` **Why.** Gemini CLI's configuration docs map `httpUrl` to Streamable HTTP and `url` to the older SSE transport. Both Amplitude servers speak Streamable HTTP, and the Docs server supports nothing else, so don't copy a generic MCP snippet that uses a bare `url` into a hand-edited entry. The `gemini mcp add --transport http` commands above handle this for you: they write the URL with `"type": "http"`. 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: Prompt for Gemini CLI ```text 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: Prompt for Gemini CLI ```text 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. **Why.** The Amplitude MCP server isn't an ingestion endpoint and never sends your app's events. It's how Gemini reads your taxonomy and checks results; the SDK still does the sending. The Docs server is what stops Gemini from writing a package name from training data. ## 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: .env.local ```sh 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`. **Why.** Gemini CLI respects `.gitignore` when it searches your project, and env files are almost always ignored. If the agent can't see an env file, it tends to create a new one or put the key in source. Naming the variable in the prompt, as step 3 does, avoids both. The project API key is public and its scope is limited to the minimum needed to ingest data, so it isn't a secret the way a server credential is, but a key hardcoded in source lives forever in forks and Git history. ## 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. Prompt for Gemini CLI ```text 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. src/lib/amplitude.ts ```typescript 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: Prompt for Gemini CLI ```text 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. Prompt for Gemini CLI ```text 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: src/features/reports/ExportButton.tsx (inside the click handler, after the export succeeds) ```typescript import { track } from "@amplitude/unified"; track("Report Exported", { format }); ``` **MCP.** Gemini can also add the new event to your tracking plan with `manage_amp_events` if your Amplitude role has the **Use MCP (write)** permission and the Update Tracking Plan permission in Amplitude Data. Gemini CLI shows the tool call before it runs, so read the event name and properties in that confirmation before you approve it. ## 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: Prompt for Gemini CLI ```text 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. GEMINI.md ```markdown ## 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](https://amplitude.com/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](https://amplitude.com/heatmaps), built from those same session replays, show where people clicked on the reports page before they exported. - [Feature Experiment](https://amplitude.com/amplitude-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](https://amplitude.com/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 [Web frameworksAdd product analytics to a React appWhat the correct browser install looks like, file by file, so you can check Gemini's work against it.](/build/react-product-analytics)[AI coding toolsAdd product analytics to your app with Claude CodeThe same workflow in Anthropic's terminal agent, with the Amplitude plugin and the rules saved in CLAUDE.md.](/build/claude-code-product-analytics)[AI coding toolsAdd analytics to your app with Codex CLIThe same workflow in OpenAI's Codex CLI, with the rules saved in AGENTS.md.](/build/codex-cli-analytics) Reference docs [Connect Amplitude MCP to Gemini CLI →](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/gemini-cli)[Amplitude MCP server →](https://amplitude.com/docs/amplitude-ai/amplitude-mcp)[Docs MCP server →](https://amplitude.com/docs/amplitude-ai/docs-mcp-server)[Amplitude Quickstart →](https://amplitude.com/docs/get-started/amplitude-quickstart)[Browser Unified SDK →](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk)[Debug analytics →](https://amplitude.com/docs/analytics/debug-analytics) Amplitude is the leading [all-in-one analytics platform](https://amplitude.com/) for building better products. Product and engineering teams use Amplitude to connect [product analytics](https://amplitude.com/amplitude-analytics) and [web analytics](https://amplitude.com/web-analytics) with [session replay](https://amplitude.com/session-replay), [heatmaps](https://amplitude.com/heatmaps), [experimentation](https://amplitude.com/amplitude-experiment), [feature flags](https://amplitude.com/feature-management), and [guides and surveys](https://amplitude.com/guides-and-surveys) in one unified workflow, with [AI agents](https://amplitude.com/ai-agents) working across all of it. Learn how Amplitude is building [self-improving products](https://amplitude.com/self-improving-products) with [Wave](https://amplitude.com/wave), helping teams turn product data into PRs. For agents [View raw .md](/build/gemini-cli-product-analytics.md)[llms.txt](/llms.txt) ## Ship the instrumentation, then read the data Once events are flowing, Amplitude turns them into funnels, retention curves, and session replays without any further setup. [Create a free account](https://app.amplitude.com/signup)[Browse all Build tutorials](https://amplitude.com/build)