@rezlazy/yandex-metrika-mcp

Yandex Metrika Reports API(/stat/v1/*) 및 Management API(/management/v1/*)용 MCP 서버입니다.

68개 도구를 제공합니다: 보고서 도구 6개와 관리 도구 62개(카운터, 목표, 필터, 권한, 세그먼트, 라벨 등).

요구 사항

• Node.js 20+

• metrika:read(보고서) 및/또는 metrika:write(생성/수정/삭제) 권한이 있는 OAuth 토큰

Related MCP server: Google Analytics MCP Server

OAuth 토큰 발급받기

1. Yandex OAuth 앱 만들기 — API 액세스 또는 디버깅용을 선택합니다.

2. metrika:read(보고서) 및 metrika:write(관리 변경) 권한을 추가합니다.

3. 앱의 Client ID를 복사합니다.

4. 브라우저에서 엽니다:

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

5. 리디렉션 URL(access_token=...)에서 토큰을 복사합니다.

Yandex Metrika 인증 문서를 참조하세요.

Cursor 설정

.cursor/mcp.json 또는 Cursor MCP 설정에 추가합니다:

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

로컬 개발용(이 저장소의 .cursor/mcp.json):

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

프로젝트 루트에 .env를 생성합니다:

METRIKA_TOKEN=your_oauth_token

MCP 서버 실행

서버는 HTTP가 아닌 stdio(표준 입력/출력)를 사용합니다. 웹 서버처럼 직접 시작하는 것이 아니라 MCP 클라이언트(예: Cursor)가 하위 프로세스로 실행합니다.

요구 사항: Node.js 20+, METRIKA_TOKEN, 그리고 빌드된 dist/index.js(로컬 개발용).

Cursor에서(권장)

1. .cursor/mcp.json 또는 Cursor MCP 설정에서 MCP를 구성합니다(위 예시 참조).

2. 설정 → MCP → 새로고침을 하거나 Cursor를 다시 시작합니다.

Cursor는 도구가 사용될 때 node dist/index.js(로컬) 또는 npx @rezlazy/yandex-metrika-mcp(npm)를 자동으로 실행합니다. 문제가 발생하면 출력 → MCP 로그를 확인하세요.

GitHub에서(npm 배포 없이)

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

git 설치의 경우 dist/가 저장소에 존재하거나 설치 시 빌드되어야 합니다(예: prepare 스크립트 사용).

수동 실행(디버깅 전용)

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

프로세스는 표준 입력에서 JSON-RPC를 조용히 기다립니다 — 이는 정상적인 동작입니다. METRIKA_TOKEN이 없으면 오류와 함께 종료됩니다.

다중 루트 작업 공간(*.code-workspace)

mcp.code-workspace(한 창에 여러 폴더)를 열면 Cursor가 설정 → MCP에서 .cursor/mcp.json의 프로젝트 MCP 서버를 표시하지 않을 수 있습니다. 이는 알려진 Cursor 제한 사항입니다.

해결 방법:

1. 이 저장소를 직접 엽니다: 파일 → 폴더 열기 → yandex-metrika-mcp(.code-workspace 파일이 아님).

2. 또는 전역 설정 ~/.cursor/mcp.json에 추가합니다(다중 루트에서 작동):

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

설정 변경 후: 설정에서 MCP를 새로고침하거나 Cursor를 다시 시작합니다. 로그 확인: 출력 패널 → MCP 로그.

환경 변수

도구

보고서(stat_*) — 6개 도구

관리(mgmt_*) — 62개 도구

Management API를 다룹니다: 카운터, 목표, 필터, 연산, 권한, 액세스 필터, 세그먼트, 차트 주석, 라벨, 계정, 대리인, 클라이언트, 클라우드 내보내기.

일반적인 관리 도구:

POST/PUT 메서드의 경우 body 매개변수에 JSON을 전달합니다(API 형식 참조). 카운터 생성 예시:

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

보고서 매개변수

• ids — 카운터 ID(쉼표로 구분)

• metrics — 예: ym:s:visits, ym:s:users, ym:s:pageviews

• dimensions — 예: ym:s:trafficSource, ym:s:operatingSystem

• date1 / date2 — 기간(7daysAgo, today 또는 YYYY-MM-DD)

• filters — 세그먼테이션 표현식

• preset — 보고서 프리셋

• format — json(기본값) 또는 csv

전체 메트릭 및 차원 목록: attrandmetr.

예시: 트래픽 소스별 방문 수

도구: 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"
}

예시: 일별 방문 추세

도구: stat_bytime

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

개발

npm install
npm run typecheck
npm test
npm run build

npm 배포

배포는 GitHub Release가 게시될 때 GitHub Actions를 통해 자동화됩니다.

일회성 설정:

1. npmjs.com에서 npm 조직/스코프 @rezlazy를 생성합니다.

2. npm Automation 토큰을 생성합니다.

3. GitHub 저장소에 NPM_TOKEN 시크릿을 추가합니다.

4. 태그 v0.1.0으로 릴리스를 생성합니다 — 워크플로가 @rezlazy/yandex-metrika-mcp를 배포합니다.

라이선스

MIT