CDP MCP 서버

Acquia **고객 데이터 플랫폼(Customer Data Platform)**을 LLM에서 바로 사용할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. Claude, Copilot 또는 MCP를 지원하는 모든 클라이언트를 이 서버에 연결하면 테넌트 읽기, 캠페인 실행, 워크플로우 확인, 보고서 쿼리 등 지루한 관리 작업을 대신 수행할 수 있습니다.

새벽 2시에 CDP 화면을 클릭하며 작업하는 것이 즐거운 일은 아니라는 생각에서 제작되었습니다.

제공 기능

• ~300개의 도구: 권한, 데이터 웨어하우스, 캠페인, 구성, 커넥터, 보고서, 예측, 메일러, 이메일 발송 가능 페이지, 보안, 캐시 및 상태 API를 포괄합니다. 전체 목록은 SUPPORTED_TOOLS.md를 참조하세요.

• 8개의 플레이북 리소스: LLM이 실제 다단계 흐름(캠페인 마법사, C360 프로필 렌더링, 워크플로우 작성, 커넥터 온보딩, UDMP 스키마 편집 등)을 순차적으로 수행하는 방법을 학습합니다. 이는 Vega 및 구성 UI를 리버스 엔지니어링하여 모델이 추측하지 않도록 설계되었습니다.

• 두 가지 인증 모드: OAuth2 비밀번호 부여(자동 갱신, 401 재시도, 잠금 직렬화) 또는 이미 토큰이 있는 경우 정적 베어러 토큰을 사용할 수 있습니다.

• Dev / QA / Prod 전환: CDP_ENVIRONMENT 변수 하나로 간단히 전환 가능합니다.

• Stdio 전송: Claude Desktop, VS Code Copilot, Continue, mcphost, Open WebUI(supergateway 경유) 또는 MCP Inspector에서 바로 사용할 수 있습니다.

위 내용이 생소하다면 TUTORIAL.md를 훑어보세요. 복사하여 붙여넣을 수 있는 명령어로 각 부분을 설명합니다. 도구 이름과 기능에 대한 전체 목록은 SUPPORTED_TOOLS.md를 참조하세요.

빠른 시작

# 1. Clone and install
git clone https://github.com/atharva-joshi77/cdp-mcp.git
cd cdp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Configure
cp .env.example .env
# edit .env: CDP_ENVIRONMENT, CDP_TENANT_ID, and either
#   CDP_CLIENT_ID/SECRET + CDP_USERNAME/PASSWORD  (OAuth2)
# or CDP_AUTH_TOKEN                                (static token)

# 3. Run
cdp-mcp

cdp-mcp는 stdio에서 JSON-RPC를 사용하므로, 그냥 실행하면 멈춘 것처럼 보일 수 있습니다. 이는 정상입니다. MCP 클라이언트(아래 참조)에 연결하면 작동하기 시작합니다.

Claude Desktop에 연결

~/Library/Application Support/Claude/claude_desktop_config.json 파일:

{
  "mcpServers": {
    "cdp": {
      "command": "/absolute/path/to/cdp-mcp/.venv/bin/cdp-mcp",
      "env": {
        "CDP_ENVIRONMENT": "dev",
        "CDP_TENANT_ID": "12345",
        "CDP_CLIENT_ID": "...",
        "CDP_CLIENT_SECRET": "...",
        "CDP_USERNAME": "...",
        "CDP_PASSWORD": "..."
      }
    }
  }
}

Claude를 재시작하면 도구 선택기에서 약 300개의 cdp_* 도구가 나타나는 것을 볼 수 있습니다. VS Code, Continue, Ollama/Open WebUI 및 MCP Inspector 설정에 대한 전체 레시피는 TUTORIAL.md §5에 있습니다.

요구 사항

종속성(자동 설치):

• mcp>=1.13.0 — FastMCP 프레임워크

• httpx>=0.27.0 — 비동기 HTTP

• pydantic + pydantic-settings — 구성 + 유효성 검사

• python-dotenv — .env 로딩

프로젝트 구조

src/cdp_mcp/
├── __main__.py           # entry point: `cdp-mcp` / `python -m cdp_mcp`
├── server.py             # FastMCP server, registers tools + resources
├── config.py             # env/.env loader
├── auth/                 # OAuth2 + static-token provider
├── utils/                # shared httpx client, error helpers
├── resources/            # MCP resource URIs (tenant/*, docs/*)
├── docs/                 # the eight playbooks, shipped as resources
├── types/                # pydantic request/response models
└── tools/                # one subpackage per CDP service area
    ├── permissions/      users, roles, clients
    ├── dw/               data warehouse, A360, audiences, offers, trackers
    ├── campaign/         defs, audiences, messages, dispatches, runs, exports
    ├── config_api/       tenants, workflows, schedules, UDMP, DQE, clusters…
    ├── connectors/       input + output connectors, templates
    ├── reports/          dashboards, widgets, cubes, QL
    ├── predictions/      prediction defs + content templates
    ├── mailer/           accounts, subusers, identifiers, batches
    ├── emailable_pages/  emailable-pages CRUD
    ├── security/         token, auth, SSO, password reset
    ├── cache/            cache ops
    ├── spam/             spam score
    ├── status/           status + orchestration/purge status
    ├── provisions/       self-service provisioning
    ├── global_actions/   platform-wide actions
    └── alerts/           stub (real Alerts API lives in a different stack)

모든 도구는 풀링된 httpx 연결, 공유 인증 토큰 캐시, 갱신 시 asyncio.Lock, 1회성 401 재시도, URL 인코딩된 테넌트 ID 및 logger.info 요청/응답 추적을 포함하는 단일 HttpClient를 공유합니다. 문제가 발생하면 로그를 확인하는 것이 가장 정확합니다.

플레이북 (핵심 기능)

도구 목록만으로는 충분하지 않습니다. 많은 CDP 흐름은 "정의 POST, 그 다음 ?action=publish POST, 그 다음 상태 GET, 그 다음 별도의 일정 ID로 ?action=schedule POST"와 같은 복잡한 과정을 거칩니다. LLM은 이를 스스로 처리할 경우 자주 실수합니다.

따라서 이 서버는 8개의 마크다운 플레이북을 MCP 리소스로 제공합니다:

MCP 클라이언트는 연결 시 이를 자동으로 검색하며, 서버의 instructions 블록이 모델에게 각 리소스를 안내합니다.

인증 참고 사항

• OAuth2 (권장): 공급자가 헤더에 자격 증명을 포함하여 POST {baseUrl}/token?action=create를 호출하고, 토큰을 메모리에 캐시하며, 동시 갱신을 asyncio.Lock으로 직렬화하고, 만료 60초 전에 갱신합니다. 하위 호출에서 401이 발생하면 1회성 강제 갱신 및 재시도가 트리거됩니다.

• 정적 토큰: CDP_AUTH_TOKEN을 설정하면 OAuth2 경로가 완전히 건너뛰어집니다. 이 경우 토큰 교체는 직접 관리해야 합니다.

실제 비밀 정보를 이 저장소에 넣지 마십시오. .env는 gitignore 처리되어 있습니다.

개발

# smoke test: should print the server's capabilities + tool list
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | cdp-mcp

# interactive tool browser
npx @modelcontextprotocol/inspector cdp-mcp

# verify tool count
python3 -c "from cdp_mcp.server import create_server; import asyncio; \
  print(len(asyncio.run(create_server().list_tools())))"

더 자세한 문제 해결 매트릭스(서버 시작 실패, 401 오류, 클라이언트 연결 불가 등)는 TUTORIAL.md §9에 있습니다.

상태

• 도구 수: 12개 CDP 서비스에 걸쳐 301개

• 플레이북 리소스: 8개

• 경고(Alerts) 도구는 의도적으로 스텁 처리됨 — 실제 경고 API는 별도의 MuleSoft/Go 스택에 있으며 자체 기본 URL과 인증이 필요함 (PR 환영)

• 통합 테스트 하네스는 개발 중 (스캐폴딩은 존재하며, 전체 계약 범위는 후속 작업으로 추적됨)

기여

1. 포크, 브랜치 생성 및 작업.

2. ./gradlew-equivalent 실행 (또는 pip install -e . 및 위의 스모크 테스트 실행).

3. 도구를 추가하는 경우, 일치하는 tools/<area>/__init__.py 등록기에 연결.

4. 다단계 흐름을 추가하는 경우, src/cdp_mcp/docs/ 아래에 플레이북을 작성하고 resources/resource_providers.py에 리소스를 등록.

5. PR을 제출. 설명에 친절하게 작성해주세요.

라이선스

내부/독점 — 자체 테넌트 외부에서 사용하기 전에 Acquia에 확인하십시오.

httpx, pydantic 그리고 불안정한 CDP 마법사에 대한 분노를 동등한 비율로 섞어 제작되었습니다.