JUHE API Marketplace
39world avatar
MCP Server

OpenStack MCP Server

Modern and stable Model Context Protocol server that enables controlling OpenStack through natural language commands via Claude Desktop.

0
GitHub Stars
10/3/2025
Last Updated
MCP Server Configuration
1{
2 "name": "openstack-mcp",
3 "command": "poetry",
4 "args": [
5 "run",
6 "python",
7 "src/main.py"
8 ],
9 "cwd": "/path/to/ktc-openstack-mcp",
10 "env": {
11 "MCP_MOCK_MODE": "false",
12 "OPENSTACK_AUTH_URL": "http://your-openstack: 5000/v3",
13 "OPENSTACK_USERNAME": "admin",
14 "OPENSTACK_PASSWORD": "your_password"
15 }
16}
JSON16 lines

README Documentation

OpenStack MCP Server

OpenStack을 자연어로 제어할 수 있는 MCP(Model Context Protocol) 서버입니다. Claude Desktop과 연동하여 OpenStack 리소스를 대화형으로 관리할 수 있습니다.

빠른 시작

Mock 모드 (OpenStack 없이 테스트)

# 의존성 설치
poetry install

# Mock 모드로 실행
MCP_MOCK_MODE=true poetry run python src/main.py --mock-mode

실제 OpenStack 연결

# 환경변수 설정
export OPENSTACK_AUTH_URL=http://your-openstack:5000/v3
export OPENSTACK_USERNAME=admin
export OPENSTACK_PASSWORD=your_password
export OPENSTACK_PROJECT_NAME=admin

# 서버 실행
poetry run python src/main.py

설치

사전 요구사항

  • Python 3.10+
  • Poetry
  • Claude Desktop (MCP 연동용)
  • OpenStack 환경 (Mock 모드에서는 불필요)

설치 과정

git clone <repository-url>
cd ktc-openstack-mcp
poetry install

환경설정

환경변수를 통해 설정을 관리합니다. .env.example 파일을 참고하세요.

필수 환경변수 (실제 OpenStack 연결시)

# OpenStack 인증 정보
OPENSTACK_AUTH_URL=http://controller:5000/v3
OPENSTACK_USERNAME=admin
OPENSTACK_PASSWORD=secure_password
OPENSTACK_PROJECT_NAME=admin
OPENSTACK_USER_DOMAIN_NAME=Default
OPENSTACK_PROJECT_DOMAIN_NAME=Default

# 선택 사항
OPENSTACK_REGION_NAME=RegionOne
OPENSTACK_INTERFACE=public

MCP 서버 설정

# Mock 모드 (기본값: false)
MCP_MOCK_MODE=true

# 로그 레벨 (기본값: INFO)
MCP_LOG_LEVEL=DEBUG

# 전송 방식 (기본값: stdio)
MCP_TRANSPORT=stdio

# HTTP 모드일 때 포트 (기본값: 8000)
MCP_HTTP_PORT=8000

Claude Desktop 연동

설정 파일 위치

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

설정 예시

{
  "mcpServers": {
    "openstack-mcp": {
      "command": "poetry",
      "args": ["run", "python", "src/main.py"],
      "cwd": "/path/to/ktc-openstack-mcp",
      "env": {
        "MCP_MOCK_MODE": "false",
        "OPENSTACK_AUTH_URL": "http://your-openstack:5000/v3",
        "OPENSTACK_USERNAME": "admin",
        "OPENSTACK_PASSWORD": "your_password"
      }
    }
  }
}

명령줄 옵션

# Mock 모드
poetry run python src/main.py --mock-mode

# 디버그 모드
poetry run python src/main.py --debug

# 로그 레벨 설정
poetry run python src/main.py --log-level DEBUG

# HTTP 모드 (기본: stdio)
poetry run python src/main.py --transport http --http-port 8080

# 도움말
poetry run python src/main.py --help

프로젝트 구조

ktc-openstack-mcp/
├── src/
│   ├── main.py                   # 진입점
│   ├── config/
│   │   └── settings.py          # Pydantic 기반 설정
│   ├── core/
│   │   ├── mcp_server.py        # MCP 서버 구현
│   │   ├── base_client.py       # OpenStack 클라이언트 기반 클래스
│   │   ├── mock_client.py       # Mock 클라이언트
│   │   └── clients/             # OpenStack API 클라이언트들
│   ├── tools/                   # MCP 도구 구현
│   └── api/                     # REST API (추가 기능)
├── k8s/                         # Kubernetes 배포 설정
├── scripts/                     # 빌드/배포 스크립트
├── general_index.md             # 프로젝트 파일 구조 개요
├── detailed_index.md            # 클래스/함수 상세 분석
└── test_sdk_import.py           # 통합 테스트

개발 및 테스트

테스트 실행

# SDK 임포트 테스트
python test_sdk_import.py

# 서버 건강 상태 확인
poetry run python src/main.py --mock-mode &
# 서버가 정상 시작되면 Ctrl+C로 종료

개발 도구

아키텍처

핵심 컴포넌트

  • MCP Server: FastMCP 기반의 MCP 프로토콜 구현
  • OpenStack Clients: 각 서비스별 분리된 클라이언트 (Compute, Image, Network, Volume)
  • Mock Client: 실제 OpenStack 없이 테스트 가능한 Mock 구현
  • Tools: 27개의 MCP 도구로 OpenStack 기능 제공

주요 기능

  • 서버 관리 (생성, 시작, 중지, 재시작, 삭제)
  • 이미지 조회 및 관리
  • 네트워크 및 포트 관리
  • 볼륨 생성 및 연결
  • 연결 상태 진단
  • Mock 모드 지원

기술 스택

  • FastMCP: MCP 서버 프레임워크
  • OpenStack SDK: OpenStack API 클라이언트
  • Pydantic Settings: 환경변수 기반 설정 관리
  • Poetry: 의존성 관리
  • Uvicorn: ASGI 서버 (HTTP 모드용)

Kubernetes 배포

프로덕션 환경에서 Kubernetes를 통해 배포할 수 있습니다.

사전 준비


# containerd 환경에서
nerdctl build -t openstack-mcp-server:latest .

설정 파일 수정

배포하기 전에 k8s/ 디렉토리의 설정 파일들을 수정해야 합니다.

1. ConfigMap 수정 (일반 설정)

# k8s/configmap.yaml 파일을 직접 수정

주요 설정 항목:

  • MCP_MOCK_MODE: Mock 모드 설정 ("true" 또는 "false")
  • OPENSTACK_AUTH_URL: OpenStack 인증 URL
  • OPENSTACK_REGION_NAME: 리전 설정
  • 기능별 활성화/비활성화 설정

2. Secret 수정 (민감한 정보)

# k8s/secret.yaml 파일을 직접 수정

중요: Secret 파일의 값들을 base64로 인코딩해야 합니다:

# 인코딩 방법
echo -n "your_username" | base64    # OPENSTACK_USERNAME
echo -n "your_password" | base64    # OPENSTACK_PASSWORD  
echo -n "your_project" | base64     # OPENSTACK_PROJECT_NAME

3. Pod 환경변수 동작 방식

Deployment에서 환경변수는 다음과 같이 로드됩니다:

# k8s/deployment.yaml
envFrom:
- configMapRef:
    name: openstack-mcp-config    # ConfigMap의 모든 키-값 로드
- secretRef:
    name: openstack-mcp-secrets   # Secret의 모든 키-값 로드

배포 방법

자동 배포 스크립트 사용

# 1. 설정 파일 수정 (위 섹션 참조)
#    - k8s/configmap.yaml 수정
#    - k8s/secret.yaml 수정 (base64 인코딩 필요)

# 2. 배포 실행
chmod +x scripts/build-and-deploy.sh

# default 네임스페이스에 배포
./scripts/build-and-deploy.sh

# 특정 네임스페이스에 배포
./scripts/build-and-deploy.sh -n production
./scripts/build-and-deploy.sh --namespace dev

# 도움말 확인
./scripts/build-and-deploy.sh --help

수동 배포

# 1. 설정 파일 수정 (위 섹션 참조)

# 2. 리소스 배포
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

# 3. 배포 상태 확인
kubectl rollout status deployment/openstack-mcp-server

배포 후 확인

# Pod 상태 확인
kubectl get pods -l app=openstack-mcp-server

# 로그 확인
kubectl logs -f deployment/openstack-mcp-server

# Service 상태 확인
kubectl get svc openstack-mcp-service

# Health Check 테스트 (Port Forward)
kubectl port-forward svc/openstack-mcp-service 4000:4000
curl http://localhost:4000/health

환경별 설정 예시

Mock 모드로 배포 (개발/테스트)

# k8s/configmap.yaml에서
data:
  MCP_MOCK_MODE: "true"
  OPENSTACK_AUTH_URL: "mock://localhost"
# k8s/secret.yaml에서 (값은 실제로 사용되지 않음)
data:
  OPENSTACK_USERNAME: "YW55X3VzZXI="  # any_user (base64)
  OPENSTACK_PASSWORD: "YW55X3Bhc3M="  # any_pass (base64)
  OPENSTACK_PROJECT_NAME: "YW55X3Byb2plY3Q="  # any_project (base64)

프로덕션 모드로 배포

# k8s/configmap.yaml에서
data:
  MCP_MOCK_MODE: "false"
  OPENSTACK_AUTH_URL: "https://your-production-openstack:5000/v3"
  OPENSTACK_REGION_NAME: "your-region"
# k8s/secret.yaml에서 (실제 값을 base64로 인코딩)
data:
  OPENSTACK_USERNAME: "cHJvZF91c2Vy"        # prod_user (base64)
  OPENSTACK_PASSWORD: "cHJvZF9wYXNzd29yZA=="  # prod_password (base64)
  OPENSTACK_PROJECT_NAME: "cHJvZF9wcm9qZWN0"   # prod_project (base64)

접근 방법

클러스터 내부 접근

# 다른 Pod에서 접근
curl http://openstack-mcp-service:3000

# Health Check
curl http://openstack-mcp-service:4000/health

외부 접근 (개발/테스트용)

# Port Forward 사용
kubectl port-forward svc/openstack-mcp-service 3000:3000
# 브라우저나 curl로 접근
curl http://localhost:3000

리소스 정리

# 모든 리소스 삭제
kubectl delete -f k8s/

# 또는 개별 삭제
kubectl delete deployment openstack-mcp-server
kubectl delete service openstack-mcp-service
kubectl delete configmap openstack-mcp-config
kubectl delete secret openstack-mcp-secrets

라이센스

MIT License

참고 문서

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source

Boost your projects with Wisdom Gate LLM API

Supporting GPT-5, Claude-4, DeepSeek v3, Gemini and more.

Enjoy a free trial and save 20%+ compared to official pricing.