@rezlazy/yandex-metrika-mcp

MCP-Server für die Yandex-Metrika-Reports-API (/stat/v1/*) und die Management-API (/management/v1/*).

Stellt 68 Tools bereit: 6 Report-Tools und 62 Management-Tools (Zähler, Ziele, Filter, Zugriffsrechte, Segmente, Labels und mehr).

Voraussetzungen

• Node.js 20+

• OAuth-Token mit metrika:read (Reports) und/oder metrika:write (Erstellen/Aktualisieren/Löschen)

Related MCP server: Google Analytics MCP Server

Ein OAuth-Token erhalten

1. Erstellen Sie eine Yandex-OAuth-App – wählen Sie Für API-Zugriff oder Debugging.

2. Fügen Sie die Berechtigungen metrika:read (Reports) und metrika:write (Management-Änderungen) hinzu.

3. Kopieren Sie die Client-ID der App.

4. Öffnen Sie im Browser:

   https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>

5. Kopieren Sie das Token aus der Weiterleitungs-URL (access_token=...).

Siehe Yandex-Metrika-Autorisierungsdokumentation.

Cursor-Konfiguration

Fügen Sie zu .cursor/mcp.json oder den Cursor-MCP-Einstellungen hinzu:

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "@rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

Für die lokale Entwicklung (.cursor/mcp.json in diesem Repository):

{
  "mcpServers": {
    "yandex-metrika": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Erstellen Sie .env im Projektstammverzeichnis:

METRIKA_TOKEN=your_oauth_token

Den MCP-Server ausführen

Der Server verwendet stdio (stdin/stdout), nicht HTTP. Sie starten ihn nicht wie einen Webserver – Ihr MCP-Client (z. B. Cursor) startet ihn als untergeordneten Prozess.

Voraussetzungen: Node.js 20+, METRIKA_TOKEN und eine gebaute dist/index.js (für lokale Entwicklung).

In Cursor (empfohlen)

1. Konfigurieren Sie MCP in .cursor/mcp.json oder den Cursor-MCP-Einstellungen (siehe Beispiele oben).

2. Einstellungen → MCP → Aktualisieren, oder starten Sie Cursor neu.

Cursor führt node dist/index.js (lokal) oder npx @rezlazy/yandex-metrika-mcp (npm) automatisch aus, wenn Tools verwendet werden. Prüfen Sie Ausgabe → MCP-Protokolle, wenn etwas fehlschlägt.

Von GitHub (ohne npm-Veröffentlichung)

{
  "mcpServers": {
    "yandex-metrika": {
      "command": "npx",
      "args": ["-y", "github:Rezlazy/yandex-metrika-mcp"],
      "env": {
        "METRIKA_TOKEN": "<your-oauth-token>"
      }
    }
  }
}

Bei Git-Installationen muss dist/ im Repository vorhanden sein oder bei der Installation gebaut werden (z. B. über ein prepare-Skript).

Manuelle Ausführung (nur zum Debuggen)

npm run build
export METRIKA_TOKEN=your_oauth_token
node dist/index.js

Der Prozess wartet still auf JSON-RPC über stdin – das ist erwartet. Ohne METRIKA_TOKEN wird mit einem Fehler beendet.

Multi-Root-Arbeitsbereich (*.code-workspace)

Wenn Sie mcp.code-workspace öffnen (mehrere Ordner in einem Fenster), zeigt Cursor möglicherweise keine Projekt-MCP-Server aus .cursor/mcp.json unter Einstellungen → MCP an. Dies ist eine bekannte Cursor-Einschränkung.

Problemumgehungen:

1. Dieses Repository direkt öffnen: Datei → Ordner öffnen → yandex-metrika-mcp (nicht die .code-workspace-Datei).

2. Oder zur globalen Konfiguration hinzufügen ~/.cursor/mcp.json (funktioniert im Multi-Root-Modus):

"yandex-metrika": {
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/yandex-metrika-mcp/dist/index.js"],
  "envFile": "/absolute/path/to/yandex-metrika-mcp/.env"
}

Nach Konfigurationsänderungen: Aktualisieren Sie MCP in den Einstellungen oder starten Sie Cursor neu. Prüfen Sie die Protokolle: Ausgabefeld → MCP-Protokolle.

Umgebungsvariablen

Tools

Reports (stat_*) – 6 Tools

Management (mgmt_*) – 62 Tools

Umfasst die Management-API: Zähler, Ziele, Filter, Operationen, Zugriffsrechte, Zugriffsfilter, Segmente, Diagrammanmerkungen, Labels, Konten, Delegierte, Clients, Cloud-Exporte.

Häufige Management-Tools:

Für POST/PUT-Methoden übergeben Sie JSON im Parameter body (siehe API-Formate). Beispiel zum Erstellen eines Zählers:

{
  "body": {
    "counter": {
      "name": "My site",
      "site": "example.com"
    }
  }
}

Report-Parameter

• ids – Zähler-ID(s), durch Kommas getrennt

• metrics – z. B. ym:s:visits, ym:s:users, ym:s:pageviews

• dimensions – z. B. ym:s:trafficSource, ym:s:operatingSystem

• date1 / date2 – Zeitraum (7daysAgo, today oder YYYY-MM-DD)

• filters – Segmentierungsausdruck

• preset – Report-Voreinstellung

• format – json (Standard) oder csv

Vollständige Liste der Metriken und Dimensionen: attrandmetr.

Beispiel: Besuche nach Verkehrsquelle

Tool: stat_data

{
  "ids": "44147844",
  "metrics": "ym:s:visits,ym:s:users",
  "dimensions": "ym:s:trafficSource",
  "date1": "30daysAgo",
  "date2": "today",
  "sort": "-ym:s:visits",
  "limit": "10"
}

Beispiel: Täglicher Besuchsverlauf

Tool: stat_bytime

{
  "ids": "44147844",
  "metrics": "ym:s:visits",
  "date1": "30daysAgo",
  "date2": "today",
  "group": "day"
}

Entwicklung

npm install
npm run typecheck
npm test
npm run build

Veröffentlichung auf npm

Die Veröffentlichung wird automatisiert über GitHub Actions durchgeführt, wenn eine GitHub-Version veröffentlicht wird.

Einmalige Einrichtung:

1. Erstellen Sie die npm-Organisation/den Scope @rezlazy auf npmjs.com.

2. Generieren Sie ein npm-Automation-Token.

3. Fügen Sie das Geheimnis NPM_TOKEN zum GitHub-Repository hinzu.

4. Erstellen Sie eine Version mit dem Tag v0.1.0 – der Workflow veröffentlicht @rezlazy/yandex-metrika-mcp.

Lizenz

MIT