KakaoCloud OpenAPI MCP Server

카카오클라우드 OpenAPI 문서를 AI 코딩 어시스턴트(Claude Code, Codex 등)에서 쉽게 활용할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

왜 필요한가?

카카오클라우드에서 VM을 만들거나 VPC를 구성할 때, API 문서를 일일이 찾아가며 코딩하는 것은 번거롭습니다.

이 MCP 서버를 설치하면 AI 어시스턴트가 자동으로 카카오클라우드 API 정보를 조회하여 정확한 코드를 생성해줍니다.

사용자: "카카오클라우드에서 VM 만드는 파이썬 스크립트 작성해줘"

AI → MCP 서버에서 VM 생성 API 정보 조회
AI → VPC, Subnet, Security Group, Keypair 등 사전 조건 파악
AI → 인증 방법 포함한 완전한 파이썬 스크립트 생성

지원 서비스

서비스	설명	엔드포인트 수
BCS (Beyond Compute Service)	VM, 볼륨, 이미지, 스냅샷, 키페어 (인스턴스 상태 변경 통합 액션 API 포함)	54
VPC	VPC, 서브넷, 보안 그룹, 라우트 테이블, 공인 IP	28
Load Balancer	로드 밸런서, 리스너, 대상 그룹 (생성 시 대상 그룹/리스너 동시 구성 지원)	6
Transit Gateway	VPC 간 네트워크 연결	4
Container Pack	관리형 Kubernetes (K8s Engine)	16
Data Store	관리형 MySQL	18

총 126개 API 엔드포인트 + 5개 워크플로우 가이드

모든 OpenAPI 호출은 카카오클라우드 CloudTrail에 자동 기록되며, 콘솔에서 'OpenAPI' 서비스 이벤트로 조회할 수 있습니다.

설치

요구 사항

• Python 3.12+
• uv (Python 패키지 매니저)

방법 1: PyPI에서 설치 (추천)

별도 클론 없이 바로 사용할 수 있습니다.

# uv가 없다면 먼저 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

설치 확인:

uvx kakaocloud-openapi-mcp --help

방법 2: GitHub에서 설치

소스코드를 직접 받아서 사용하거나 수정하고 싶을 때 사용합니다.

# 저장소 클론
git clone https://github.com/chals-go/kakaocloud-openapi-mcp.git
cd kakaocloud-openapi-mcp

# 의존성 설치
uv sync

MCP 클라이언트 설정

Claude Code (CLI)

PyPI 설치 (추천):

claude mcp add kakaocloud -- uvx kakaocloud-openapi-mcp

GitHub 설치:

claude mcp add kakaocloud -- uv --directory /path/to/kakaocloud-openapi-mcp run kakaocloud-openapi-mcp

Claude Desktop

claude_desktop_config.json 파일에 추가:

PyPI 설치 (추천):

{
  "mcpServers": {
    "kakaocloud": {
      "command": "uvx",
      "args": ["kakaocloud-openapi-mcp"]
    }
  }
}

GitHub 설치:

{
  "mcpServers": {
    "kakaocloud": {
      "command": "uv",
      "args": ["--directory", "/path/to/kakaocloud-openapi-mcp", "run", "kakaocloud-openapi-mcp"]
    }
  }
}

설정 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

VS Code (Copilot / Continue)

.vscode/settings.json에 추가:

PyPI 설치 (추천):

{
  "mcp": {
    "servers": {
      "kakaocloud": {
        "command": "uvx",
        "args": ["kakaocloud-openapi-mcp"]
      }
    }
  }
}

GitHub 설치:

{
  "mcp": {
    "servers": {
      "kakaocloud": {
        "command": "uv",
        "args": ["--directory", "/path/to/kakaocloud-openapi-mcp", "run", "kakaocloud-openapi-mcp"]
      }
    }
  }
}

Cursor

Cursor Settings > MCP에서 추가하거나, .cursor/mcp.json에:

PyPI 설치 (추천):

{
  "mcpServers": {
    "kakaocloud": {
      "command": "uvx",
      "args": ["kakaocloud-openapi-mcp"]
    }
  }
}

GitHub 설치:

{
  "mcpServers": {
    "kakaocloud": {
      "command": "uv",
      "args": ["--directory", "/path/to/kakaocloud-openapi-mcp", "run", "kakaocloud-openapi-mcp"]
    }
  }
}

MCP 도구 (Tools)

MCP 서버는 5개의 도구를 제공합니다. AI 어시스턴트가 자동으로 적절한 도구를 선택하여 호출합니다.

1. search_kakaocloud_api

키워드로 카카오클라우드 API를 검색합니다. 한국어와 영어 모두 지원합니다.

입력: { "query": "VM 생성" }
출력: 관련 API 엔드포인트 목록 (서비스, method, path, 설명)

사용 예시:

• "VM 생성" → BCS 인스턴스 생성 API + 관련 워크플로우
• "load balancer" → 로드 밸런서 관련 API 목록
• "보안 그룹" → VPC 보안 그룹 CRUD API 목록

2. get_api_detail

특정 API 엔드포인트의 상세 스펙을 조회합니다.

입력: { "service": "bcs", "endpoint_id": "create-instance" }
출력: 파라미터, 요청/응답 바디, 전체 URL, 인증 방법, 예제

서비스 별칭 지원:

• vm, instance, compute → BCS
• vpc, 네트워크 → VPC
• lb, 로드밸런서 → Load Balancer
• k8s, kubernetes → Container Pack
• mysql, db → Data Store

3. get_service_overview

서비스의 전체 개요와 엔드포인트 목록을 조회합니다.

입력: { "service": "vm" }
출력: 서비스 설명, Base URL, 전체 엔드포인트 테이블, 관련 서비스

4. get_workflow

특정 작업의 전체 API 호출 흐름을 단계별로 안내합니다.

입력: { "task": "VM 인스턴스 생성" }
출력: 인증 → VPC → 서브넷 → 보안 그룹 → 키페어 → 인스턴스 생성 순서

제공 워크플로우:

워크플로우	설명
create-vm	VM 인스턴스 생성 (VPC/서브넷/보안그룹/키페어 포함)
create-vpc-network	VPC 네트워크 전체 구성
setup-load-balancer	로드 밸런서 설정 (대상 그룹, 리스너 포함)
create-k8s-cluster	Kubernetes 클러스터 생성 및 노드 풀 구성
create-mysql-db	관리형 MySQL 데이터베이스 생성

5. get_auth_guide

카카오클라우드 API 인증 방법을 안내합니다.

입력: (없음)
출력: 토큰 발급 방법, 코드 예제 (Python, curl), 토큰 사용법

MCP 리소스 (Resources)

정적 참조 데이터를 Resource URI로 조회할 수 있습니다.

URI	설명
kakaocloud://services	전체 서비스 목록 (JSON)
kakaocloud://service/{name}	특정 서비스의 전체 API 스펙 (JSON)
kakaocloud://auth	인증 가이드 데이터 (JSON)

실제 사용 예시

아래는 Claude Code에 이 MCP를 연결한 후 실제로 대화한 내용입니다.

VM 생성 스크립트 만들기

사용자 요청:

카카오클라우드에 vm을 만드는 python 스크립트 만들어줘,
test-vpc, test-subnet1에 만들어주고
우분투 24.04, 윈도우 2022 두개 만들거고
vm이름은 test-ubuntu, test-window 로 해줘
그리고 security group은 test-ubuntu-sg, test-window-sg 로 만들고
ubuntu 서버는 22port 인바운드, 윈도우서버는 3389 인바운드 설정되게 해줘

AI가 MCP를 통해 자동으로 수행한 작업:

1. get_workflow("VM 인스턴스 생성") → 인증 → VPC 조회 → 보안 그룹 → 인스턴스 생성 흐름 파악
2. get_auth_guide() → IAM 토큰 발급 코드 작성
3. get_api_detail("bns-vpc", "create-security-group") → 보안 그룹 생성 파라미터 확인
4. get_api_detail("bns-vpc", "create-security-group-rule") → 인바운드 규칙 파라미터 확인
5. get_api_detail("bcs", "create-instance") → VM 생성 필수 파라미터 확인

AI가 생성한 코드:

<details> <summary><b>create_vms.py</b> (클릭하여 펼치기)</summary>

"""
카카오클라우드 VM 생성 스크립트
- test-vpc / test-subnet1 에 Ubuntu 24.04, Windows 2022 VM 2대 생성
- 각 VM에 보안 그룹 생성 및 인바운드 규칙 설정
"""

import os
import sys
import requests

# ──────────────────────────────────────────────
# 설정값 (환경변수 또는 직접 입력)
# ──────────────────────────────────────────────
ACCESS_KEY_ID = os.environ.get("KAKAO_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID")
SECRET_KEY = os.environ.get("KAKAO_SECRET_KEY", "YOUR_SECRET_KEY")

UBUNTU_2404_IMAGE_ID = os.environ.get("UBUNTU_2404_IMAGE_ID", "YOUR_UBUNTU_24.04_IMAGE_ID")
WINDOWS_2022_IMAGE_ID = os.environ.get("WINDOWS_2022_IMAGE_ID", "YOUR_WINDOWS_2022_IMAGE_ID")

KEY_NAME = os.environ.get("KAKAO_KEY_NAME", "YOUR_KEYPAIR_NAME")
FLAVOR = os.environ.get("KAKAO_FLAVOR", "m2a.large")

# ──────────────────────────────────────────────
# API 엔드포인트
# ──────────────────────────────────────────────
IAM_URL = "https://iam.kakaocloud.com/identity/v3/auth/tokens"
BNS_BASE = "https://bns.kr-central-2.kakaocloud.com/api/v1"
BCS_BASE = "https://bcs.kr-central-2.kakaocloud.com/api/v1"

HEADERS = {"Content-Type": "application/json"}


def get_token():
    """IAM 인증 토큰 발급"""
    payload = {
        "auth": {
            "identity": {
                "methods": ["application_credential"],
                "application_credential": {
                    "id": ACCESS_KEY_ID,
                    "secret": SECRET_KEY,
                },
            }
        }
    }
    resp = requests.post(IAM_URL, json=payload, headers=HEADERS)
    resp.raise_for_status()
    token = resp.headers["X-Subject-Token"]
    print("[OK] 토큰 발급 완료")
    return token


def auth_headers(token):
    return {"X-Auth-Token": token, "Content-Type": "application/json"}


def find_vpc(token, name="test-vpc"):
    """VPC 이름으로 ID 조회"""
    resp = requests.get(f"{BNS_BASE}/vpcs", headers=auth_headers(token))
    resp.raise_for_status()
    for vpc in resp.json().get("vpcs", []):
        if vpc.get("name") == name:
            print(f"[OK] VPC 발견: {name} ({vpc['id']})")
            return vpc["id"]
    sys.exit(f"[ERROR] VPC '{name}'을 찾을 수 없습니다.")


def find_subnet(token, name="test-subnet1"):
    """서브넷 이름으로 ID 조회"""
    resp = requests.get(f"{BNS_BASE}/subnets", headers=auth_headers(token))
    resp.raise_for_status()
    for subnet in resp.json().get("subnets", []):
        if subnet.get("name") == name:
            print(f"[OK] Subnet 발견: {name} ({subnet['id']})")
            return subnet["id"]
    sys.exit(f"[ERROR] Subnet '{name}'을 찾을 수 없습니다.")


def create_security_group(token, name, vpc_id, description=""):
    """보안 그룹 생성"""
    payload = {"name": name, "vpc_id": vpc_id, "description": description}
    resp = requests.post(f"{BNS_BASE}/security-groups", json=payload, headers=auth_headers(token))
    resp.raise_for_status()
    sg = resp.json()
    sg_id = sg.get("id") or sg.get("security_group", {}).get("id")
    print(f"[OK] 보안 그룹 생성: {name} ({sg_id})")
    return sg_id


def add_inbound_rule(token, sg_id, port):
    """보안 그룹에 TCP 인바운드 규칙 추가"""
    payload = {
        "direction": "inbound",
        "protocol": "tcp",
        "port_range_min": port,
        "port_range_max": port,
        "remote_ip_prefix": "0.0.0.0/0",
    }
    resp = requests.post(f"{BNS_BASE}/security-groups/{sg_id}/rules", json=payload, headers=auth_headers(token))
    resp.raise_for_status()
    print(f"[OK] 인바운드 규칙 추가: port {port} (0.0.0.0/0)")


def create_instance(token, name, image_id, subnet_id, sg_id, key_name=None):
    """VM 인스턴스 생성"""
    payload = {
        "instance_name": name,
        "image_id": image_id,
        "flavor": FLAVOR,
        "networks": [{"subnet_id": subnet_id, "security_groups": [sg_id]}],
    }
    if key_name:
        payload["key_name"] = key_name

    resp = requests.post(f"{BCS_BASE}/instances", json=payload, headers=auth_headers(token))
    resp.raise_for_status()
    instance = resp.json()
    instance_id = instance.get("id") or instance.get("instance", {}).get("id")
    print(f"[OK] 인스턴스 생성 요청: {name} ({instance_id})")
    return instance_id


def main():
    print("=" * 50)
    print("카카오클라우드 VM 생성 스크립트")
    print("=" * 50)

    # 1. 인증
    token = get_token()

    # 2. VPC / Subnet 조회
    vpc_id = find_vpc(token, "test-vpc")
    subnet_id = find_subnet(token, "test-subnet1")

    # 3. 보안 그룹 생성
    print("\n--- 보안 그룹 생성 ---")
    ubuntu_sg_id = create_security_group(token, "test-ubuntu-sg", vpc_id, "Ubuntu SSH 접근용")
    add_inbound_rule(token, ubuntu_sg_id, 22)

    windows_sg_id = create_security_group(token, "test-window-sg", vpc_id, "Windows RDP 접근용")
    add_inbound_rule(token, windows_sg_id, 3389)

    # 4. VM 인스턴스 생성
    print("\n--- VM 인스턴스 생성 ---")
    ubuntu_id = create_instance(token, "test-ubuntu", UBUNTU_2404_IMAGE_ID, subnet_id, ubuntu_sg_id, KEY_NAME)
    windows_id = create_instance(token, "test-window", WINDOWS_2022_IMAGE_ID, subnet_id, windows_sg_id)

    # 5. 결과 요약
    print("\n" + "=" * 50)
    print("생성 완료 요약")
    print("=" * 50)
    print(f"  Ubuntu VM   : test-ubuntu  ({ubuntu_id})")
    print(f"    - 이미지  : Ubuntu 24.04")
    print(f"    - 보안그룹: test-ubuntu-sg (SSH 22)")
    print(f"  Windows VM  : test-window  ({windows_id})")
    print(f"    - 이미지  : Windows Server 2022")
    print(f"    - 보안그룹: test-window-sg (RDP 3389)")
    print(f"  VPC         : test-vpc ({vpc_id})")
    print(f"  Subnet      : test-subnet1 ({subnet_id})")
    print("=" * 50)
    print("\n※ 인스턴스 생성은 비동기 처리됩니다. 콘솔에서 상태를 확인하세요.")


if __name__ == "__main__":
    main()

</details>

실행 방법:

# 환경변수 설정
export KAKAO_ACCESS_KEY_ID="발급받은_ACCESS_KEY_ID"
export KAKAO_SECRET_KEY="발급받은_SECRET_KEY"
export UBUNTU_2404_IMAGE_ID="Ubuntu_24.04_이미지_ID"
export WINDOWS_2022_IMAGE_ID="Windows_2022_이미지_ID"
export KAKAO_KEY_NAME="SSH_키페어_이름"

# 실행
pip install requests
python create_vms.py

스크립트 동작 흐름:

1. IAM 토큰 발급
2. test-vpc, test-subnet1 이름으로 VPC/Subnet ID 조회
3. 보안 그룹 생성
   ├── test-ubuntu-sg → TCP 22 (SSH) 인바운드
   └── test-window-sg → TCP 3389 (RDP) 인바운드
4. VM 인스턴스 생성
   ├── test-ubuntu  — Ubuntu 24.04 + SSH 키페어
   └── test-window  — Windows Server 2022

사용자는 한 줄의 요청만 했지만, AI가 MCP를 통해 카카오클라우드 API의 인증 방식, 엔드포인트 URL, 파라미터 형식을 자동으로 파악하여 바로 실행 가능한 스크립트를 생성했습니다.

다른 요청 예시

# VPC 네트워크 구성
"카카오클라우드에서 VPC를 만들고, 퍼블릭/프라이빗 서브넷을 구성하는 코드를 작성해줘."

# Kubernetes 클러스터 배포
"카카오클라우드에서 Kubernetes 클러스터를 생성하고, 워커 노드 3대로 구성하는 스크립트를 만들어줘."

# MySQL 데이터베이스 생성
"카카오클라우드에서 MySQL 8.0 데이터베이스를 생성하는 코드 작성해줘."

# 로드 밸런서 설정
"카카오클라우드에서 로드 밸런서를 만들고 2대의 웹 서버에 트래픽을 분산하는 코드 작성해줘."

개발

테스트 실행

uv run pytest tests/ -v

MCP Inspector로 디버깅

uv run mcp dev src/kakaocloud_mcp/server.py

MCP Inspector가 브라우저에서 열리며, 각 도구를 직접 호출하고 결과를 확인할 수 있습니다.

서버 직접 실행

uv run kakaocloud-openapi-mcp

서버는 stdio 모드로 동작하므로, MCP 클라이언트가 stdin/stdout을 통해 통신합니다.

프로젝트 구조

kakaocloud-openapi-mcp/
├── pyproject.toml                    # 프로젝트 설정 및 의존성
├── src/
│   └── kakaocloud_mcp/
│       ├── server.py                 # MCP 서버 진입점
│       ├── tools/                    # MCP Tool 구현
│       │   ├── search.py             # search_kakaocloud_api
│       │   ├── detail.py             # get_api_detail
│       │   ├── overview.py           # get_service_overview
│       │   ├── workflow.py           # get_workflow
│       │   └── auth.py               # get_auth_guide
│       ├── resources/
│       │   └── services.py           # MCP Resource 핸들러
│       ├── data/
│       │   ├── loader.py             # JSON 데이터 로더 + 검색 인덱스
│       │   ├── auth.json             # 인증 가이드 데이터
│       │   ├── workflows.json        # 워크플로우 데이터
│       │   └── services/             # 서비스별 API 스펙 JSON
│       │       ├── bcs.json
│       │       ├── bns-vpc.json
│       │       ├── bns-load-balancer.json
│       │       ├── bns-transit-gateway.json
│       │       ├── container-pack.json
│       │       └── data-store-mysql.json
│       └── utils/
│           └── search.py             # 키워드 검색 유틸리티
└── tests/
    ├── test_search.py                # 검색 + 데이터 로더 테스트
    └── test_tools.py                 # Tool 함수 테스트

API 데이터 추가/수정

각 서비스의 API 스펙은 src/kakaocloud_mcp/data/services/ 디렉토리의 JSON 파일에 정의됩니다.

새 엔드포인트를 추가하려면:

1. 해당 서비스의 JSON 파일을 열고 endpoints 배열에 추가
2. keywords 필드에 한국어/영어 검색 키워드를 충분히 포함
3. uv run pytest tests/ -v 로 테스트 통과 확인

엔드포인트 구조:

{
  "id": "create-instance",
  "method": "POST",
  "path": "/instances",
  "summary": "VM 인스턴스 생성",
  "summaryKo": "VM 인스턴스 생성",
  "keywords": ["vm 생성", "인스턴스 만들기"],
  "parameters": [],
  "requestBody": { ... },
  "responses": { "202": { "description": "..." } }
}

참고

• 카카오클라우드 OpenAPI 문서
• MCP (Model Context Protocol)
• 카카오클라우드 콘솔

라이선스

MIT License