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 인증 URLOPENSTACK_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