---
title: "How to add product analytics to your app with Claude Code"
description: "Connect Claude Code to Amplitude's MCP servers and plugin, have it install the right SDK, review the diff, and save the rules in CLAUDE.md."
canonical: "https://amplitude.com/en-us/build/claude-code-product-analytics"
---

# How to add product analytics to your app with Claude Code

Connect Claude Code to Amplitude's MCP servers and plugin, have it install the right SDK, review the diff, and save the rules in CLAUDE.md.

Source: https://amplitude.com/en-us/build/claude-code-product-analytics

---

# How to add product analytics to your app with Claude Code

Connect Claude Code to Amplitude's MCP servers and plugin, hand it one prompt that installs the SDK the docs recommend for your stack, review the diff for the mistakes agents make, and save the rules in CLAUDE.md. About 15 minutes, all copy-paste.

- Claude Code
- Amplitude MCP
- Amplitude plugin
- CLAUDE.md
- 15 min

Chris Tam · Last updated 6 October 2026

Claude Code is Anthropic's coding 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 docs and your real event names instead of guessing.

In this tutorial, you'll [connect Claude Code to Amplitude](https://amplitude.com/mcp), install the Amplitude plugin, have Claude install the SDK, review its diff, and save the rules in CLAUDE.md.

## What you'll build

A Claude Code setup connected to the Amplitude MCP server and the Docs MCP server, the Amplitude plugin with its instrumentation skills, an app instrumented with the SDK the Quickstart recommends for its stack, one `Teammate Invited` event named to match your existing taxonomy, and a `CLAUDE.md` that keeps Claude on those conventions. By the end you'll see live events in your Amplitude project.

## Prerequisites

- Claude Code installed and signed in.
- A web or Node.js project in a Git repository, so you can review and revert Claude's changes with `git diff`.
- 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 covers every step except multi-branch tracking plans, which need a Growth or Enterprise plan. [Sign up for free](https://app.amplitude.com/signup) to get your project API key.

## 1. Connect Claude Code 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 [Claude Code setup guide](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/claude-code) and the [Docs MCP server page](https://amplitude.com/docs/amplitude-ai/docs-mcp-server) are the sources for both commands.

Terminal

```sh
claude mcp add -t http -s user Amplitude "https://mcp.amplitude.com/mcp"
claude mcp add -t http -s user amplitude-docs https://amplitude.com/docs/api/mcp
```

The `-s user` scope registers each server for your user account, so it's available in every Claude Code session. Use `-s local` instead to scope a server to this one project directory. If your Amplitude data lives in the EU region, use `https://mcp.eu.amplitude.com/mcp` in the first command; running it again with the EU URL overwrites the existing entry.

Start Claude Code at your repository root, open the MCP menu, and follow the Amplitude OAuth flow:

Prompt for Claude Code

```text
claude
/mcp
```

Then check the connection by asking Claude:

Prompt for Claude Code

```text
What Amplitude projects can I access?
```

A list of your projects means the Amplitude MCP server is connected and authenticated.

**Why.** The Amplitude MCP server isn't an ingestion endpoint and never sends your app's events. It's how Claude reads your taxonomy and checks results. The SDK still does the sending. The Docs server is what stops Claude from writing a package name from training data.

## 2. Install the Amplitude plugin

The [Amplitude plugin](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#plugins) adds skills on top of the MCP server. Two of them matter for this page: `discover-analytics-patterns` maps how analytics is already implemented in your codebase, and `add-analytics-instrumentation` reads your code, decides what to track, and produces an instrumentation plan. Run these inside Claude Code:

Prompt for Claude Code

```text
/plugin marketplace add amplitude/mcp-marketplace
/plugin install amplitude@amplitude
```

The install command opens the plugin's details. Choose a scope, and Claude Code reloads plugins for you. The plugin also bundles the US Amplitude MCP server. If you added the US URL in step 1, Claude Code connects it once, using your step 1 entry. If you use the EU URL, `/mcp` also lists `plugin:amplitude:amplitude` pointing at the US server; disable it there so Claude only uses your EU connection.

You don't need to call skills by name. Claude picks one when your request matches it, so a question like "how is analytics implemented in this repo?" is the kind of request `discover-analytics-patterns` handles.

The plugin's instrumentation skills also read an optional `.amplitude/instrumentation-agent-context.md` file at your repository root. You'll add one at the end of this page so they follow your naming rules.

## 3. Run the install prompt

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

Prompt for Claude Code

```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 an environment variable (for example
  AMPLITUDE_API_KEY, or the prefixed name this framework needs to expose it
  to the browser). Never hardcode it. Tell me the exact line to add to my
  env file.
- Initialize the SDK exactly once, at app or process startup, outside any
  render path or request handler.
- 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.
```

Claude comes back with the docs page it read, a project question, and a plan. Pick the project, approve the plan, and let it apply the change.

If your project's Setup page in Amplitude offers a coding-agent setup option, its generated prompt does the same job through [Agentic Setup](https://amplitude.com/docs/get-started/setup-wizard-cli), which also turns on autocapture and session replay for supported frameworks. Paste that prompt instead if you see it, and still run the review in step 4.

## 4. Review what Claude Code changed

Run `git diff` before you start the app. 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. **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.
4. **Duplicate page views.** No hand-written `track("Page Viewed")` next to autocapture, which tracks page views by default.
5. **Server flushing.** Every server-side `track` path ends with `await flush().promise` before shutdown or before a serverless handler returns.
6. **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.

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
  },
});
```

.env.local

```sh
VITE_AMPLITUDE_API_KEY=your-project-api-key
```

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. Keep it in the env file anyway, since a hardcoded key lives forever in forks and Git history.

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

Prompt for Claude Code

```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 the environment instead of
the literal string. Show me the diff.
```

## 5. Add an event that matches your taxonomy

This is where the MCP server and the plugin earn their setup. Ask Claude to check what already exists, in the code and in Amplitude, before it names anything.

Prompt for Claude Code

```text
I want to track when a user invites a teammate, with the role they
assigned 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 invite is actually sent, after the request
   succeeds, not in an effect or a render.
```

The first instruction is the kind of request the plugin's `discover-analytics-patterns` skill handles. If your tracking plan uses Title Case with spaces, Claude should propose `Teammate Invited`, not `teammateInvited` or `teammate_invited`. Once you confirm, it adds a single call in the invite handler:

src/features/team/InviteForm.tsx (inside the submit handler, after the invite request succeeds)

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

track("Teammate Invited", { role });
```

**MCP.** Claude can also add the new event to your tracking plan with `manage_amp_events` if your role has the **Use MCP (write)** permission and the Update Tracking Plan permission in Amplitude Data. On a Growth or Enterprise plan, ask it to create the event on a tracking-plan branch rather than main, so a teammate reviews it before it merges.

## Verify it worked

Run the app the way you normally do, load a page, send an invite, 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 `Teammate Invited` appear in the event stream within ten seconds to a minute. Click `Teammate Invited` to confirm the `role` value.
4. **Ask Claude.** With the Amplitude MCP server connected, ask it to check the data for you:

Prompt for Claude Code

```text
Using the Amplitude MCP server, look up my user profile in this project
and tell me whether "Teammate Invited" arrived in the last hour and which
role values it has.
```

## Troubleshooting

### Claude says it has no Amplitude tools

The servers didn't register, or this Claude Code session started before you added them. Run `/mcp` to see each server's status. If Amplitude is missing, run the `claude mcp add` commands from step 1 again and restart Claude Code.

### The OAuth page spins and never finishes

Close the tab after you approve access. Make sure you're signed in to only one Amplitude organization during the flow, since signing in to several can break authentication. If it still fails, disconnect the server in `/mcp` and authenticate again.

### Claude 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` (or `init` on Node.js) 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. Reads can still work. Ask an admin for write access, or make the tracking-plan change in the Amplitude UI.

## Save the rules in CLAUDE.md

Claude Code loads a project `CLAUDE.md` from the repository root at the start of every session. Put the conventions from this page there, so the next time you ask Claude to track something it follows them without the long prompt. Commit it, so your teammates' sessions follow the same rules.

CLAUDE.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.
- Read the API key from the environment. Never hardcode 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. Use a branch, not main, when the plan supports branches.
```

Change `src/lib/amplitude.ts` to the file Claude created in step 3 if it chose a different path. Keep the whole `CLAUDE.md` under about 200 lines; longer files cost context and Claude follows them less closely.

Give the plugin's instrumentation skills the same naming rules in the file they read:

.amplitude/instrumentation-agent-context.md

```markdown
# Instrumentation conventions

- Event names are Title Case, object then past-tense verb: "Teammate Invited",
  "Project Created".
- Event property names are camelCase: role, templateId.
- Import track from "@amplitude/unified". The SDK is initialized in
  src/lib/amplitude.ts.
- Fire events after the action succeeds, never on render.
```

## What this unlocks

- [Session replay](https://amplitude.com/session-replay), if you kept `sampleRate` above 0, lets you watch the session where `Teammate Invited` fired, and the plugin's `debug-replay` skill turns a replay's interaction timeline into reproduction steps inside Claude Code.
- [Heatmaps](https://amplitude.com/heatmaps), built from those same session replays, show where people clicked on the team page before they sent an invite.
- [Feature Experiment](https://amplitude.com/amplitude-experiment) can test a new invite flow with `Teammate Invited` as the success metric, and Claude can create the flag with `create_flags`.
- [Guides and surveys](https://amplitude.com/guides-and-surveys) can nudge admins who opened the team page but never fired `Teammate Invited`.

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 Claude's work against it.](/build/react-product-analytics)[Web frameworksAdd product analytics to a Node.js backendServer-side identity and flushing, the two things agents most often get wrong.](/build/nodejs-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 Claude Code →](https://amplitude.com/docs/amplitude-ai/amplitude-mcp/claude-code)[Amplitude MCP server and plugin →](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/claude-code-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)