AdMob MCP 서버

Claude를 Google AdMob API에 연결하여 광고 수익 데이터에 대한 대화형 인터페이스를 제공하는 로컬 Model Context Protocol 서버입니다.

이 서버를 사용하는 두 가지 방법:

• 로컬 stdio (한 대의 기기에서 Claude Code 사용): ./setup.sh를 실행하고 L을 선택하세요.

• Vercel + Claude.ai 커넥터 (멀티 디바이스): 위의 배지를 클릭한 후 docs/VERCEL.md를 따르세요. 또는 ./setup.sh를 실행하고 V를 선택하세요.

사전 요구 사항

• Node.js 18 이상

• AdMob API가 활성화된 Google Cloud 프로젝트

• OAuth 2.0 클라이언트 자격 증명 — 로컬 모드용 데스크톱 앱 유형, Vercel 모드용 웹 애플리케이션 유형 (Vercel 관련 설정은 docs/VERCEL.md 참조).

Related MCP server: Google Ads MCP Server

설정

1. Google OAuth 자격 증명 가져오기

1. Google API 콘솔로 이동합니다.

2. 프로젝트를 생성하거나 선택합니다.

3. API 라이브러리에서 AdMob API를 활성화합니다.

4. 사용자 인증 정보 > 사용자 인증 정보 만들기 > OAuth 클라이언트 ID로 이동합니다.

5. 데스크톱 앱을 선택하고 이름을 지정한 후 만들기를 클릭합니다.

6. JSON 다운로드를 클릭하여 클라이언트 비밀 파일(client secret)을 다운로드합니다.

7. 다운로드한 파일을 이 프로젝트의 secrets/ 폴더에 복사합니다.

2. 설치 및 구성

cd admob-mcp
./setup.sh

설치 스크립트는 다음을 수행합니다:

• Google OAuth JSON 파일을 찾아 secrets/client_secret.json으로 이름을 변경합니다.

• 종속성을 설치하고 빌드합니다.

• Google OAuth 인증을 위해 브라우저를 엽니다 (토큰은 secrets/token.json에 저장됨).

• Claude Code에 MCP 서버를 등록합니다.

업데이트된 범위(예: 다른 Google MCP를 추가한 후)로 재인증하려면:

./setup.sh --reauth

참고: Google Cloud 프로젝트의 OAuth 동의 화면이 게시되지 않은 경우(즉, 여전히 "테스트" 상태인 경우) 인증 오류가 발생합니다. 이를 해결하려면 앱을 게시하거나 Google Cloud 콘솔의 OAuth 동의 화면 > 테스트 사용자 아래에 Google 계정을 추가하세요.

수동 구성

setup.sh를 사용하지 않으려면 Claude Code MCP 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "admob": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/admob-mcp/dist/src/index.js"],
      "env": {
        "ADMOB_CREDENTIALS_PATH": "/absolute/path/to/admob-mcp/secrets/client_secret.json"
      }
    }
  }
}

커넥터 설정 (Vercel)

노트북의 Claude Code뿐만 아니라 모든 기기의 Claude.ai에서 AdMob 도구를 사용하려면 이 방법을 사용하세요.

1. 리포지토리를 포크합니다.

2. 위에서 Deploy with Vercel을 클릭합니다.

3. Vercel Storage 탭에서 Upstash Redis를 프로비저닝합니다. 코드가 사용하는 KV_* 환경 변수가 자동으로 주입됩니다. (Vercel은 독립형 "Vercel KV"를 더 이상 지원하지 않으며, Upstash가 동일한 백엔드입니다.)

4. Google Cloud OAuth 클라이언트(웹 앱)를 생성합니다. 승인된 리디렉션 URI = https://<your-deploy>.vercel.app/api/oauth/callback.

5. Vercel에 환경 변수를 설정합니다: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, OAUTH_REDIRECT_URI, CONNECTOR_TOKEN (openssl rand -hex 32로 생성). 공백이 들어가지 않도록 주의하세요.

6. https://<your-deploy>.vercel.app/api/setup을 방문하여 CONNECTOR_TOKEN을 붙여넣고, 승인을 클릭한 후 Google 로그인을 완료합니다. 이 작업은 서버가 사용자를 대신하여 AdMob 데이터를 읽을 수 있도록 권한을 부여합니다.

7. Claude.ai → 설정 → 커넥터 → 사용자 지정 커넥터 추가: URL에 https://<your-deploy>.vercel.app/api/mcp를 붙여넣고, OAuth 클라이언트 ID와 비밀은 비워둔 채 추가를 클릭한 다음 연결을 클릭합니다. 브라우저 탭이 /oauth/authorize에서 열리면 CONNECTOR_TOKEN을 한 번 붙여넣습니다. 나머지는 Claude.ai가 처리합니다.

두 가지 OAuth 흐름은 동일한 CONNECTOR_TOKEN에 의해 제어됩니다: Google ↔ 서버 (6단계) 및 Claude.ai ↔ 서버 (7단계). 문제 해결을 포함한 전체 가이드: docs/VERCEL.md.

사용법

자연어로 Claude에게 AdMob 데이터에 대해 질문하세요. 처음 사용할 때 Claude는 자동으로 list_accounts를 호출하여 AdMob 계정을 찾고 어떤 계정으로 작업할지 물어볼 것입니다. 그 후에는 적절한 도구를 사용하여 질문에 답변합니다.

도구

핵심 API 도구

보고 도구

수익 최적화 도구

프로젝트 구조

• src/index.ts — stdio 진입점 (Claude Code).

• src/tools.ts — 36개의 모든 도구 정의; registerTools(server, getClient).

• src/auth.ts — Google OAuth 도우미 (getAuthenticatedClient, authorizeViaLocalServer).

• src/token-store.ts — TokenStore 인터페이스 + FileTokenStore (로컬) + KvTokenStore (Vercel KV).

• src/oauth-store.ts — 커넥터 OAuth 흐름을 위한 KV 기반 저장소 (인증 코드 + 액세스 토큰).

• src/http-auth.ts — HTTP 엔드포인트를 위한 타이밍 안전 베어러 검사 (CONNECTOR_TOKEN과 동기화, KV 발급 액세스 토큰과 비동기화).

• src/admob-client.ts, src/helpers.ts — REST 클라이언트 및 보고서 서식 유틸리티.

• api/mcp.ts — Vercel 함수: HTTP MCP 엔드포인트 (스트리밍 가능 HTTP, 베어러 제한, 401 시 WWW-Authenticate 방출).

• api/setup.ts — Vercel 함수: Google ↔ 서버 OAuth 흐름을 시작하는 양식.

• api/oauth/callback.ts — Vercel 함수: Google의 리디렉션 URI; KV에 토큰 저장.

• api/oauth/authorize.ts, api/oauth/token.ts, api/oauth/register.ts — PKCE 및 동적 클라이언트 등록을 사용하여 Claude.ai ↔ 서버 OAuth 2.1 흐름을 구현하는 Vercel 함수.

• api/well-known/oauth-authorization-server.ts, api/well-known/oauth-protected-resource.ts — Claude.ai가 OAuth 엔드포인트를 검색할 수 있도록 하는 RFC 8414 / RFC 9728 메타데이터.

• setup.sh — 대화형 설정 스크립트 ([L]ocal / [V]ercel / [B]oth).

• docs/VERCEL.md — 포커 배포 가이드.

• AGENTS.md — 표준 프로젝트 노트 (CLAUDE.md는 이에 대한 심볼릭 링크).

개발

npm run build     # Compile TypeScript
npm run start     # Run the server directly (stdio)