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