CUBRID MCP Server

CUBRID 데이터베이스의 스키마를 탐색하고 읽기 전용 SQL을 실행하는 Model Context Protocol(MCP) 서버입니다. 순수 Node.js 프로젝트입니다.

요구사항

• Node.js 18 이상
• CUBRID 10.2 이상
• 접근 가능한 CUBRID Broker 포트(기본값 33000)

설치 없이 실행 환경을 확인할 수 있습니다.

npx -y cubrid-mcp --check

MCP 클라이언트 설정

Claude Desktop, Cursor 등 stdio MCP 클라이언트의 설정에 다음 서버를 추가합니다.

{
  "mcpServers": {
    "cubrid": {
      "command": "npx",
      "args": ["-y", "cubrid-mcp"],
      "env": {
        "CUBRID_HOST": "localhost",
        "CUBRID_PORT": "33000",
        "CUBRID_DATABASE": "your_database",
        "CUBRID_USER": "readonly_user",
        "CUBRID_PASSWORD": "your_password",
        "POLICY_ALLOWED_SCHEMA": "readonly_schema"
      }
    }
  }
}

Windows에서 클라이언트가 npx를 찾지 못하면 command를 npx.cmd로 변경합니다. -y는 최초 설치 확인 메시지가 MCP stdio 통신을 방해하지 않도록 합니다.

기존 Java 서버 설정과 호환되도록 JDBC URL 형식도 지원합니다.

{
  "env": {
    "CUBRID_JDBC_URL": "jdbc:cubrid:db.example.com:33000:your_database:::?charSet=utf-8",
    "CUBRID_USER": "readonly_user",
    "CUBRID_PASSWORD": "your_password"
  }
}

환경 변수

이름	필수	설명
CUBRID_HOST	조건부	CUBRID 호스트. CUBRID_JDBC_URL 사용 시 생략 가능
CUBRID_PORT	아니요	Broker 포트, 기본값 33000
CUBRID_DATABASE	조건부	데이터베이스명. CUBRID_JDBC_URL 사용 시 생략 가능
CUBRID_USER	예	CUBRID 사용자명
CUBRID_PASSWORD	아니요	CUBRID 비밀번호, 기본값은 빈 문자열
CUBRID_JDBC_URL	조건부	기존 설정 호환용 JDBC 형식 URL
POLICY_ALLOWED_SCHEMA	아니요	접근을 허용할 스키마, 기본값은 사용자명
POLICY_HARD_MAX_ROWS	아니요	쿼리 최대 행 수, 기본값 10000
POLICY_HARD_MAX_BYTES	아니요	결과 최대 바이트 수, 기본값 20971520
POLICY_HARD_TIMEOUT_MS	아니요	쿼리 제한 시간, 기본값 30000
CUBRID_CONNECTION_TIMEOUT_MS	아니요	연결 제한 시간, 기본값 10000

.env 파일

npx를 실행하는 작업 폴더에 .env 파일을 두면 연결 설정을 자동으로 읽습니다. .env.example을 .env로 복사한 뒤 실제 접속 정보를 입력하세요. .env는 .gitignore에 포함되어 GitHub에 업로드되지 않습니다.

연결 정보는 npm 패키지에 저장되지 않으며 실행 환경에서만 전달됩니다.

제공 기능

• db.ping: 데이터베이스 연결 확인
• db.listTables: 테이블과 뷰 목록 조회
• db.describeTable: 컬럼, 기본 키, 인덱스 조회
• db.query: 정책 범위 안에서 SELECT 쿼리 실행
• 스키마 요약, 테이블 상세, SQL 정책 MCP 리소스

서버는 공식 MCP TypeScript SDK와 네이티브 CAS 프로토콜 기반 cubrid-client를 사용합니다. stdout은 MCP 메시지에만 사용합니다.

보안

db.query는 단일 SELECT/읽기 전용 CTE만 허용하고, 다른 스키마 참조와 SQL 주석 및 쓰기 키워드를 차단합니다. 애플리케이션 정책은 완전한 SQL 방화벽이 아니므로 실제 운영에서는 반드시 조회 권한만 가진 전용 CUBRID 계정을 사용하세요.

개발 및 테스트

npm install
npm test
npm run check

Java 빌드 단계는 없습니다. npm 패키지에 bin/, src/, package.json, README, 라이선스만 포함됩니다.

npm 배포

게시 전 패키지 이름과 포함 파일을 확인합니다.

npm view cubrid-mcp
npm pack --dry-run
npm login
npm whoami
npm publish --access public

npm publish 전에 테스트가 자동 실행됩니다. 이후 릴리스는 변경 범위에 맞게 버전을 올린 뒤 게시합니다.

npm version patch
npm publish --access public

npm의 2단계 인증이 활성화되어 있으면 게시 과정에서 OTP 또는 인증 절차가 추가로 필요합니다. cubrid-mcp 이름은 실제 게시 시점까지 예약되지 않습니다.

라이선스

MIT