LinkedIn Campaign Manager MCP

LinkedIn Marketing API용 MCP 서버 — Claude에서 평이한 영어로 캠페인, 성과 및 리드 생성 양식을 쿼리하세요.

광고 계정, 캠페인, 크리에이티브, 성과 분석, 인구 통계, 동영상 분석, 예산 페이싱, 기간 비교, 전환, 리드 생성 양식, 타겟 오디언스 및 타겟팅 패싯을 다루는 19개의 읽기 전용 도구입니다. LinkedIn에서 스폰서 콘텐츠, 리드 생성 양식 및 계정 기반 캠페인을 운영하는 B2B 유료 소셜 팀을 위해 구축되었습니다.

존재 이유

LinkedIn Marketing API는 다루기가 매우 까다롭기로 유명합니다. 매월 바뀌는 Rosetta 버전 관리, 문서화되지 않은 필드 매핑, 분석을 위한 Rest.li 스타일의 중첩 쿼리 매개변수, 그리고 조용히 만료되는 60일 액세스 토큰 등이 그 이유입니다. 이 서버는 이러한 복잡한 과정을 내부적으로 처리하므로, 사용자는 dateRange=(start:(year:...))와 같은 코드를 직접 작성할 필요 없이 평이한 영어로 질문할 수 있습니다.

LinkedIn 광고를 위한 다른 오픈 소스 MCP 서버 중 이 정도의 깊이를 제공하는 것은 없습니다. 대부분은 "캠페인 목록 조회" 수준에서 멈춥니다. 이 서버는 인구 통계, 동영상 완료 퍼널, 예산 페이싱, 기간 비교, 그리고 Marketo나 Salesforce와 리드를 대조할 수 있도록 PII가 포함된 리드 생성 양식 응답까지 포함합니다.

프롬프트 예시

설치 후 Claude에게 다음과 같이 질문해 보세요:

• "지난 28일간의 LinkedIn 광고 지출 추이를 캠페인 그룹별로 보여줘."

• "이번 달과 지난달의 경쟁사 공략 캠페인 CPL을 비교해줘. 어떤 크리에이티브가 성과를 견인했어?"

• "가장 지출이 많은 캠페인의 인구 통계를 가져와줘. 어떤 직급과 산업군이 전환되고 있어?"

• "지난달 가장 높은 제출률을 기록한 리드 생성 양식은 무엇이며, 리드당 비용은 얼마였어?"

• "인지도 캠페인의 동영상 완료 퍼널을 보여줘. 사람들이 어디에서 이탈하고 있어?"

• "예산 초과 위험이 있는 캠페인이 있어? 활성화된 모든 캠페인의 예산 페이싱을 보여줘."

• "어제 리드 생성 양식 응답을 가져와줘. Marketo 데이터와 대조해볼게."

데모

🎥 워크스루 영상 곧 공개 예정 — Claude Code에서 60초 이내에 LinkedIn 캠페인 성과를 쿼리하는 방법.

도구

설정

1. 설치

npm install -g linkedin-campaign-manager-mcp

또는 로컬에서 클론 및 빌드:

git clone https://github.com/ZLeventer/linkedin-campaign-manager-mcp
cd linkedin-campaign-manager-mcp
npm install
npm run build

2. LinkedIn 개발자 앱 생성

Marketing API는 제한되어 있습니다. 특정 제품 승인이 포함된 LinkedIn 개발자 앱이 필요합니다.

1. developer.linkedin.com으로 이동 → 앱 생성 (회사 페이지와 연결).

2. 제품 탭 — 다음 항목에 대한 액세스 요청:

   • Marketing Developer Platform (r_ads, r_ads_reporting 포함)

   • Lead Gen Forms 또는 Community Management API (r_ads_leadgen_automation 포함)

3. LinkedIn이 앱 액세스를 수동으로 검토합니다 (보통 2~6주 소요).

4. 인증 탭 → 승인된 리디렉션 URL — 다음 추가: http://127.0.0.1:53123 (LINKEDIN_OAUTH_PORT를 다르게 설정한 경우 해당 포트로 변경).

5. 인증 탭에서 클라이언트 ID와 클라이언트 시크릿을 복사합니다.

제품 승인 없이는 모든 API 호출이 403 오류를 반환합니다. 서버는 정상적으로 컴파일되고 시작되지만, 403은 코드 문제가 아닌 앱 수준의 권한 문제입니다.

3. 환경 설정

cp .env.example .env
# edit .env with your LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET,
# LINKEDIN_DEFAULT_AD_ACCOUNT (numeric ID from Campaign Manager URL)

4. 승인 (일회성 OAuth 흐름)

npm run auth

이 명령은 포트 53123(또는 LINKEDIN_OAUTH_PORT)에서 로컬 HTTP 서버를 열고, 터미널에 인증 URL을 출력한 뒤 OAuth 콜백을 기다립니다. 브라우저에서 승인하면 코드를 액세스 토큰 + 365일 갱신 토큰으로 교환하여 token.json(모드 0600)에 저장합니다.

갱신 토큰이 만료되는 경우(365일 후)에만 npm run auth를 다시 실행하면 됩니다.

5. Claude Code(또는 기타 MCP 클라이언트)에 연결

~/.claude.json의 mcpServers 아래에 추가:

{
  "mcpServers": {
    "linkedin": {
      "command": "linkedin-campaign-manager-mcp",
      "env": {
        "LINKEDIN_CLIENT_ID": "your_client_id",
        "LINKEDIN_CLIENT_SECRET": "your_client_secret",
        "LINKEDIN_TOKEN_PATH": "/absolute/path/to/token.json",
        "LINKEDIN_DEFAULT_AD_ACCOUNT": "123456789",
        "LINKEDIN_API_VERSION": "202504"
      }
    }
  }
}

또는 소스에서 실행하는 경우:

{
  "mcpServers": {
    "linkedin": {
      "command": "node",
      "args": ["/path/to/linkedin-campaign-manager-mcp/dist/index.js"],
      "env": {
        "LINKEDIN_CLIENT_ID": "...",
        "LINKEDIN_CLIENT_SECRET": "...",
        "LINKEDIN_TOKEN_PATH": "/path/to/token.json",
        "LINKEDIN_DEFAULT_AD_ACCOUNT": "123456789"
      }
    }
  }
}

Claude Code를 재시작하세요. 19개의 도구가 linkedin 서버 아래에 나타납니다.

환경 변수

URN 처리

LinkedIn 리소스는 URN으로 식별됩니다: urn:li:sponsoredAccount:123, urn:li:sponsoredCampaign:456 등.

모든 도구 입력은 일반 숫자 ID 또는 전체 URN을 허용하며, 클라이언트가 자동으로 숫자 ID를 URN으로 래핑합니다. 숫자 ID는 캠페인 관리자 URL(/accounts/<id>/, /campaigns/<id>/)에서 확인할 수 있습니다.

날짜 입력

모든 날짜 매개변수는 다음을 허용합니다:

기본 범위: 28daysAgo → yesterday.

LinkedIn 관련 주의사항

API 버전 변경

LinkedIn Rosetta는 월별 버전(202504 = 2025년 4월)을 사용합니다. 버전은 출시 후 약 12개월이 지나면 지원이 중단되며, 이때 410 Gone 오류가 발생합니다. 분기별로 LINKEDIN_API_VERSION을 업데이트하세요. 버전 관리 문서를 참조하세요.

분석 쿼리 형태

/adAnalytics는 일반 ISO 문자열이 아닌 Rest.li 스타일의 중첩 매개변수를 사용합니다:

dateRange=(start:(year:2024,month:10,day:1),end:(year:2024,month:10,day:31))
campaigns=List(urn:li:sponsoredCampaign:123,urn:li:sponsoredCampaign:456)

이는 dateRangeParam() 및 liGetRaw()에 의해 내부적으로 처리됩니다. 서버를 확장하는 경우, 수동으로 빌드된 URL과 함께 liGetRaw()를 통해 분석 호출을 라우팅하세요. URLSearchParams가 중첩된 괄호를 망가뜨릴 수 있으므로 분석 엔드포인트에는 liGet()을 사용하지 마세요.

분석 데이터 지연

LinkedIn 분석은 대부분의 지표에서 2~6시간, 전환 데이터의 경우 최대 24시간까지 지연됩니다. 어제 수치는 보통 완료된 상태이며, 오늘의 수치는 부분적입니다.

60일 액세스 토큰, 365일 갱신 토큰

액세스 토큰은 60일, 갱신 토큰은 365일 후에 만료됩니다. 클라이언트는 필요할 때마다 모든 요청에서 액세스 토큰을 자동으로 갱신합니다. 갱신 토큰이 만료되면 npm run auth를 다시 실행하세요.

리드 생성 응답 PII

li_get_leadgen_responses는 이름, 이메일, 회사, 직함과 같은 실제 리드 PII를 반환합니다. 출력물을 민감하게 취급하세요. 공유 로그, 암호화되지 않은 저장소 또는 공개 채널에 기록하지 마세요. LinkedIn의 데이터 사용 정책에 따라 리드가 명시적으로 동의하지 않는 한, 수신 후 90일 이내에 리드 응답을 삭제해야 합니다. 이 도구는 승인된 CRM 대조(Marketo/SFDC) 용도로만 사용해야 합니다.

속도 제한

LinkedIn은 공식적인 속도 제한 수치를 공개하지 않습니다. 실제로는 앱당 분당 약 100회의 분석 호출에서 제한이 발생할 수 있습니다. 429 오류 발생 시 재시도 로직은 포함되어 있지 않으므로, 제한에 도달하면 호출 빈도를 줄이거나 클라이언트 측에서 결과를 캐싱하세요.

이 서버를 사용하지 말아야 할 때

• 캠페인, 예산 또는 크리에이티브 생성/수정 — 설계상 읽기 전용입니다. 캠페인 생성은 자동화하기에 너무 많은 실패 요인이 있으므로 캠페인 관리자 UI를 사용하세요.

• 실시간 노출 데이터 — 거의 실시간 데이터를 보려면 LinkedIn Insight Tag + GA4를 사용하세요.

• 임의 타겟팅 기준에 대한 오디언스 크기 추정 — 임시 크기 측정을 위해서는 캠페인 관리자 오디언스 빌더 UI를 사용하세요. li_get_audience_insights는 저장/업로드된 세그먼트의 크기만 반환합니다.

라이선스

MIT © 2026 Zach Leventer