Connecting Yandex Metrica to Claude Code via MCP: A Complete Setup Guide

How I got my AI coding assistant to query web analytics data directly from the terminal — — and the one gotcha that cost me two hours.

If you’ve been using Claude Code for any serious development work, you’ve probably noticed how the Model Context Protocol (MCP) is quietly becoming the connective tissue between AI assistants and the tools we actually use. MCP is an open standard that lets AI models talk to external services through a structured server interface — — think of it as a universal adapter between your AI assistant and the rest of your toolchain.

I’ve had Google Analytics 4 connected to Claude Code for a while, and it’s been genuinely useful. Being able to ask “what were my top landing pages last week?” without leaving the terminal saves more context-switching than you’d expect. So when I discovered that someone had built a Yandex Metrica MCP server, I wanted to set it up immediately.

The value proposition is straightforward: instead of opening the Yandex Metrica dashboard, navigating through reports, and manually cross-referencing data with your codebase, you can ask Claude Code questions like “show me traffic sources for the last 30 days” or “what’s the bounce rate on mobile devices” and get structured data right in your development session. You can then use that data to inform decisions about performance optimization, content strategy, or feature prioritization — — all without breaking your flow.

The setup itself is not complicated. But there is one critical step in the OAuth application creation process that is poorly documented and will absolutely block you if you don’t know about it. That’s the real reason I wrote this article.

Prerequisites

Before we start, make sure you have:

• Node.js 18+ installed (check with node --version)
• Claude Code CLI installed and working (you should be able to run claude in your terminal)
• A Yandex account with at least one Metrica counter set up and collecting data
• Basic terminal knowledge — — you’ll need to clone a repo, run npm commands, and edit a URL or two

If you don’t have a Yandex Metrica counter yet, go to metrika.yandex.com, create one, and add the tracking code to your site. You’ll need at least a few days of data for the tools to return meaningful results.

Step 1: Clone and Build the MCP Server

The MCP server we’re using is atomkraft/yandex-metrika-mcp on GitHub. It’s a TypeScript project that wraps the Yandex Metrica Reporting API into 25 MCP-compatible tools.

# Clone the repository
git clone https://github.com/nicholasxuu/yandex-metrika-mcp.git

# Navigate into the project
cd yandex-metrika-mcp

# Install dependencies
npm install

# Build the TypeScript source
npx tsc

After the build completes, you’ll have a build/ directory with the compiled JavaScript. The entry point is build/index.js.

The server exposes 25 tools organized into logical categories: traffic analysis, demographics, content analytics, e-commerce metrics, search engine data, and more. Each tool maps to a specific Yandex Metrica API endpoint and returns structured JSON data that Claude Code can interpret and reason about.

Tip: If you get TypeScript errors during the build, make sure you’re running Node.js 18 or later. The project uses modern TypeScript features that won’t compile on older versions.

Step 2: Create a Yandex OAuth Application

This is the step that will either take you five minutes or two hours, depending on whether you read this section carefully. I learned the hard way.

The Problem with the International Portal

Your first instinct will be to go to the international OAuth portal at oauth.yandex.com and create an application there. Don't do this. Or rather, you can --- but the application you create will not have the permissions you need.

The international .com portal (oauth.yandex.com/client/new) only allows you to create "Web services" type applications. When you look at the Data Access section of the app configuration, you'll see permissions for Yandex ID --- things like avatar, email, birthday, and login. That's it.

There is no Metrica API scope available on the .com portal.

This is the single most common reason developers get 403 Access Denied errors when trying to use the Yandex Metrica API. The token you get from a .com application will work fine for login:info (you can verify your account details), but every Metrica API call will return a 403.

The Solution: Use the Russian .ru Portal

You must create your OAuth application on the Russian portal:

https://oauth.yandex.ru/client/new

Yes, the interface will be in Russian. Here’s what you need to do:

1. Navigate to [https://oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new)
2. Enter your app name — — this can be anything descriptive, like “Metrica MCP Server”
3. Select the application type: Choose “Для доступа к API или отладки” (For API access or debugging). This is the critical selection that unlocks API-specific scopes. The other option, “Веб-сервисы” (Web services), gives you the same limited scope set as the .com portal
4. Configure Data Access: In the “Доступ к данным” (Data access) field, type “metrika” in the search box. You’ll see metrika:read appear as an option --- select it
5. Set the redirect URI: Use https://oauth.yandex.ru/verification_code for a simple token flow
6. Create the application and note your client_id

Important: The .com portal only shows Yandex ID permissions (avatar, email, birth date) in its Data Access section. The .ru portal with "API access or debugging" type shows the full range of API scopes including metrika:read, metrika:write, direct:read, and many others. This distinction is not well-documented in the official Yandex developer docs.

Obtain Your OAuth Token

Once your application is created, get your token by visiting this URL in your browser:

https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID&force_confirm=yes

Replace YOUR_CLIENT_ID with the actual client ID from the previous step. You'll be redirected to a page showing your token. Copy it and save it somewhere secure.

The token is valid for one year (expires_in=31536000 seconds). Set a calendar reminder to refresh it before it expires, or you'll get mysterious authentication failures 12 months from now.

Step 3: Register the MCP Server in Claude Code

Now that you have a working token, register the server with Claude Code. The cleanest way to do this is with the CLI command:

claude mcp add \
  -e YANDEX_API_KEY="YOUR_TOKEN" \
  -s user \
  yandex-metrika \
  -- node /absolute/path/to/yandex-metrika-mcp/build/index.js

Let me break down the flags:

• -e YANDEX_API_KEY="YOUR_TOKEN" --- passes the OAuth token as an environment variable to the server process
• -s user --- sets the scope to "user" level, meaning this server will be available in all your Claude Code sessions, not just the current project. Use -s project if you only want it available in a specific project
• yandex-metrika --- the name you're giving this MCP server (you'll see it in claude mcp list)
• -- node /absolute/path/to/.../build/index.js --- the actual command to start the server

Warning: Use the absolute path to build/index.js, not a relative one. MCP servers are started from Claude Code's working directory, which may not be where you expect. A relative path like ./build/index.js will fail silently.

After adding the server, restart Claude Code to load the new configuration:

# Exit and relaunch Claude Code
claude

Verify the connection:

claude mcp list

You should see something like:

yandex-metrika: connected

If it shows as connected, you’re ready to go.

Step 4: Test the Connection

Let’s run a few test queries to make sure everything is working. Open Claude Code and try these:

Account Info

Ask Claude Code to check your Yandex Metrica account:

What Yandex Metrica counters do I have access to?

Claude Code will call the get_account_info tool and return a list of your counters with their IDs, names, and associated domains.

Traffic Overview

Show me daily visits for counter YOUR_COUNTER_ID for the last 7 days

This uses the get_visits tool and returns data like:

{
  "date": "2026-04-03",
  "visits": 1247,
  "users": 892,
  "bounceRate": 34.2,
  "pageDepth": 2.8,
  "avgVisitDuration": 185
}

Traffic Sources

What are the traffic source types for counter YOUR_COUNTER_ID this month?

The get_traffic_sources_types tool breaks down your traffic into categories:

• Direct — — users who typed your URL or used bookmarks
• Search engines — — organic search traffic
• Social networks — — referrals from social platforms
• Referral sites — — links from other websites
• Ad systems — — paid traffic from Yandex Direct, etc.

Each category includes visits, users, bounce rate, and conversion data.

Combining with Development Context

The real power shows up when you combine analytics data with code. For example:

Check my mobile vs desktop traffic split, then look at my CSS media 
queries and tell me if my breakpoints make sense for my actual audience.

Claude Code can pull the device data from Yandex Metrica, inspect your stylesheets, and give you a data-informed recommendation — — all in one conversation.

Troubleshooting

403 Access Denied

Cause: Your OAuth token doesn’t have the metrika:read scope.

Fix: You created your app on the .com portal, or you selected "Web services" instead of "API access or debugging" on the .ru portal. You need to create a new application on https://oauth.yandex.ru/client/new, select the correct type, add the metrika:read scope, and generate a new token.

There is no way to add scopes to an existing application after creation. You must create a new one.

Server Not Appearing in Tool List

Cause: The MCP server configuration wasn’t saved correctly, or Claude Code hasn’t been restarted.

Fix:

1. Run claude mcp list to check if the server is registered
2. If it’s not listed, re-run the claude mcp add command
3. If it’s listed but shows “disconnected,” check that the path to build/index.js is correct and absolute
4. Restart Claude Code after any configuration changes

Token Works for Account Info but Metrica Returns 403

Cause: Your token has login:info scope (from a Web services app) but not metrika:read scope (from an API access app).

Fix: The account info endpoint only needs basic authentication, but the Metrica reporting API requires the specific metrika:read scope. Create a new application on the .ru portal as described in Step 2.

“Counter not found” Errors

Cause: The counter ID doesn’t belong to the account associated with your OAuth token.

Fix: Use get_account_info first to see which counters are available under your token. Make sure you're using a counter ID from that list.

Build Fails with TypeScript Errors

Cause: Incompatible Node.js version.

Fix: Ensure you’re running Node.js 18 or later. Run node --version to check. If you're using nvm, switch with nvm use 18.

Available Tools

The server provides 25 tools organized by category:

Traffic & Visits

• get_visits — Daily visit metrics (visits, users, bounce rate, page depth, duration)
• get_data_by_time — Traffic data segmented by time intervals
• get_traffic_sources_types — Traffic breakdown by source category
• get_new_users_by_source — New user acquisition by traffic source

Demographics & Devices

• get_user_demographics — Age, gender, and interest data for visitors
• get_device_analysis — Device type, model, and screen resolution breakdown
• get_mobile_vs_desktop — Mobile/desktop/tablet traffic split
• get_browsers_report — Browser name and version usage statistics

Geographic Data

• get_regional_data — Traffic by country and region
• get_geographical_organic_traffic — Organic search traffic by geography

Content & Pages

• get_page_performance — Per-page metrics (views, time on page, exit rate)
• get_page_depth_analysis — Page depth distribution and engagement
• get_content_analytics_articles — Article-level content performance
• get_content_analytics_authors — Performance by content author
• get_content_analytics_categories — Performance by content category
• get_content_analytics_topics — Performance by content topic
• get_content_analytics_sources — Content discovery by traffic source

Search & SEO

• get_search_engines_data — Search engine distribution (Yandex, Google, etc.)
• get_organic_search_performance — Organic search metrics and trends
• sources_search_phrases — Search phrases driving traffic
• sources_summary — Overall source summary with key metrics

Conversions & E-commerce

• get_goals_conversion — Goal completion rates and conversion funnels
• get_conversion_rate_by_source_and_landing — Conversion rates segmented by source and landing page
• get_ecommerce_performance — E-commerce metrics (revenue, orders, cart data)

Advertising

• get_yandex_direct_experiment — Yandex Direct advertising experiment data

Account

• get_account_info — Account details and available counters

Conclusion

Once everything is connected, having Yandex Metrica data available directly in Claude Code feels like a natural extension of the development workflow. Instead of context-switching to a dashboard, you can ask analytical questions while you’re deep in code and get answers in seconds.

The setup process is straightforward — — clone, build, configure — — with one significant exception: the OAuth application must be created on the .ru portal with the "API access" type. This is the kind of detail that's obvious once you know it but can waste hours if you don't. I hope this article saves you that time.

If you’ve already set up Google Analytics 4 via MCP, you’ll notice the Yandex Metrica server follows a similar pattern but is actually simpler to configure — — there’s no service account JSON or Google Cloud Console project required. Just one OAuth token and you’re done. The tradeoff is the .ru portal requirement, which is a one-time hurdle.

The MCP ecosystem for analytics is growing quickly. Having multiple analytics platforms connected means you can cross-reference data sources and get a more complete picture of your site’s performance, all from the same terminal session where you’re writing code.

Tags: Claude Code, Yandex Metrica, MCP, Model Context Protocol, Analytics, Developer Tools