Meta MCP 커넥터

Graph API를 통해 Meta / Facebook Ads를 위한 평이한 언어 MCP 서버입니다.

광고 계정, 캠페인, 광고 세트, 지출 및 성과를 자연어로 질문하세요 — 테이블 이름이나 원시 API 경로가 필요 없습니다.

기능

• Facebook 마케팅 API(Graph API)의 실시간 데이터

• 상위 Business Manager와 함께 광고 계정 나열

• 캠페인 / 광고 세트 / 광고 성과(지출, 노출, 클릭, 구매)

• 계정 수준 지출 대시보드(account-spend.html)

• Cloud Run에 배포 시 Claude.ai OAuth(MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

프로젝트 구조

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

설정(로컬)

1. 클론 및 설치

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. .env 구성

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

토큰 요구 사항

• 사용자 토큰(EAA…)이어야 하며, 앱 토큰(app_id|secret)이 아님

• Graph API Explorer에서 귀하의 FACEBOOK_APP_ID에 대해 생성

• 권한: ads_read, ads_management, business_management

get-token.html을 사용하거나 서버를 실행하고 http://127.0.0.1:8001/get-token을 엽니다.

3. 서버 시작

python meta_mcp_server.py --http

4. Cursor MCP 구성

.cursor/mcp.json:

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

서버 시작 후 Cursor 설정에서 MCP를 다시 로드하세요.

MCP 도구

예시 프롬프트

• "내 Meta 광고 계정 나열"

• "2026-08-01부터 2026-08-15까지 Meta 광고 요약"

• "WOW 광고 계정의 지난 7일 일일 지출"

• "어제 지출 기준 상위 광고"

• "지난주 캠페인별 지출 분석"

Google Cloud Run

동일한 HTTP MCP 엔드포인트를 Cloud Run에 호스팅합니다(vdp-connector와 동일한 패턴). Docker 이미지는 .env 또는 비밀을 포함하지 않습니다.

사전 요구 사항

• Google Cloud SDK(gcloud) 설치 및 로그인(gcloud auth login)

• 결제가 활성화된 GCP 프로젝트

• GCP 프로젝트 ID

• 로컬 .env에 Facebook 자격 증명 준비(.env.example 참조)

배포

이 저장소 폴더에서:

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

스크립트가 수행하는 작업:

1. Cloud Run, Cloud Build, Secret Manager, Artifact Registry 활성화

2. FACEBOOK_APP_SECRET → Secret Manager(meta-facebook-app-secret) 업로드

3. .env에 설정된 경우 FACEBOOK_ACCESS_TOKEN → Secret Manager(meta-facebook-access-token) 업로드

4. --source .(Dockerfile), 환경 변수 및 비밀 주입으로 배포

5. MCP_PUBLIC_URL을 서비스 URL로 설정(Claude OAuth에 필요)

6. 커넥터 URL 출력: https://SERVICE-URL/mcp

배포 플래그:

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated(첫 배포 시 작동하는 MCP URL에 필요)

• --session-affinity, --max-instances 1, --timeout 300, --port 8080

Cursor(Cloud Run)

배포 후, 출력된 URL을 .cursor/mcp.json에 넣으세요:

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

Cloud Run을 사용할 때 로컬 python meta_mcp_server.py 프로세스는 필요하지 않습니다.

Claude 사용자 지정 커넥터

Claude.ai는 원격 사용자 지정 커넥터에 OAuth가 필요합니다. 이 서버는 MCP_PUBLIC_URL이 설정된 경우(배포 스크립트가 자동으로 설정) Claude 호환 OAuth 공급자(동적 클라이언트 등록)를 포함합니다.

1. .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"로 배포

2. 이전의 손상된 커넥터 제거

3. 설정 → 커넥터 → 사용자 지정 커넥터 추가

4. 정확히 붙여넣기: https://YOUR-CLOUD-RUN-URL/mcp(/mcp 포함해야 함)

5. 고급 설정에서 OAuth 클라이언트 ID를 비워 둡니다(DCR 활성화됨)

6. 연결 클릭 — Claude가 자체 등록하고 잠시 인증합니다

"Couldn't register with … sign-in service"(ofid_…)가 표시되면:

• URL이 /mcp로 끝나는지 확인(베어 Cloud Run 호스트가 아님)

• 서비스가 실행 중인지 확인: https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server 열기 — registration_endpoint가 있는 JSON이 표시되어야 함

• MCP_PUBLIC_URL이 서비스 원본과 일치하는지 확인(URL을 변경한 경우 재배포)

• 외부 IdP를 설정하지 않는 한 임의의 OAuth 클라이언트 ID를 붙여넣지 마십시오

배포 확인

로컬 vs 클라우드

보안 참고

--allow-unauthenticated는 Cloud Run URL을 공개적으로 접근 가능하게 만듭니다. OAuth는 도구가 작동하기 전에 Claude가 등록/인증을 완료해야 함을 의미합니다. 토큰이 없는 임의의 호출자는 401을 받습니다. 그럼에도 URL을 민감한 것으로 취급하고 널리 공유하기 전에 더 강력한 인증을 추가하세요.

일반적인 문제

1. Claude URL에 /mcp 누락 → "Couldn't connect to the server"

2. MCP_PUBLIC_URL 미설정 → OAuth 404 → "Couldn't register with sign-in service"

3. .env 또는 비밀 파일 커밋

4. OAuth 코드 변경 후 재배포 잊음

5. FACEBOOK_ACCESS_TOKEN 없이 배포 → Graph API가 권한 오류 반환

GitHub에 푸시

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

보안

• .env를 절대 커밋하지 마세요 — gitignore됨

• FACEBOOK_ACCESS_TOKEN은 비밀입니다. 노출되면 교체하세요

• Cloud Run 배포는 MCP URL 접근성을 위해 --allow-unauthenticated를 사용합니다. OAuth는 MCP_PUBLIC_URL이 설정된 경우 도구 접근을 보호합니다.