CUBRID MCP Server

CUBRID 데이터베이스에 대한 Model Context Protocol (MCP) 서버입니다. LLM/에이전트가 CUBRID 데이터베이스의 스키마를 탐색하고 SELECT 쿼리를 안전하게 실행할 수 있도록 지원합니다.

📋 목차

• 주요 기능

• 시작하기

  • 요구사항

  • 설치

  • 설정

• 사용법

  • 빌드

  • 실행

  • MCP 클라이언트 연동

• API 문서

  • Tools

  • Resources

• 보안 정책

• 테스트

• 문제 해결

• 기여하기

• 라이선스

Related MCP server: @adevguide/mcp-database-server

✨ 주요 기능

• 🔍 스키마 탐색: 테이블 목록 조회, 테이블 스키마 정보 조회

• 📊 데이터 조회: SELECT 쿼리 실행 및 결과 반환

• 🔒 보안 정책: SELECT만 허용, 지정된 스키마만 접근 가능

• 🚀 고성능: HikariCP 연결 풀 사용

• 📝 로깅: stderr로 로그 출력 (stdout은 MCP 메시지 전용)

🚀 시작하기

⚡ 빠른 시작 (컴파일된 JAR 바로 사용하기) ⭐

이 저장소의 루트에 포함된 cubrid-mcp.jar 파일을 다운로드하여 Cursor, Claude Desktop 등 MCP를 지원하는 에이전트 도구에서 컴파일 없이 즉시 사용할 수 있습니다.

1. JAR 파일 준비: cubrid-mcp.jar 파일을 다운로드하여 로컬의 적당한 경로에 위치시킵니다. (Java 17 이상 필요)

2. 에이전트 도구 등록: Cursor나 Claude Desktop의 MCP 설정에서 새 서버를 추가하고 아래 명령어를 입력합니다.

   • Command: java

   • Arguments: -Dfile.encoding=UTF-8 -jar "C:/다운로드경로/cubrid-mcp.jar"

3. 환경변수 설정: 도구의 설정 화면(env)에서 아래 정보를 직접 입력합니다. (소스 코드를 수정하거나 컴파일할 필요가 없습니다.)

   • CUBRID_JDBC_URL: jdbc:cubrid:아이피:포트:DB명:::?charSet=utf-8

   • CUBRID_USER: dba

   • CUBRID_PASSWORD: 비밀번호

요구사항

• Java: 17 이상

• Maven: 3.6 이상

• CUBRID: 데이터베이스 서버 (버전 11.x 권장)

• CUBRID JDBC 드라이버: 자동으로 Maven 저장소에서 다운로드됩니다

설치

1. 저장소 클론:

   git clone https://github.com/xhdndi81/cubrid-mcp.git
   cd cubrid-mcp

2. 의존성 확인:

   mvn dependency:resolve

   CUBRID JDBC 드라이버는 자동으로 CUBRID Maven 저장소에서 다운로드됩니다.

설정

1. 설정 파일 생성

application.yml.example 파일을 복사하여 application.yml을 생성하세요:

# Windows
copy src\main\resources\application.yml.example src\main\resources\application.yml

# Linux/Mac
cp src/main/resources/application.yml.example src/main/resources/application.yml

2. 데이터베이스 연결 정보 설정

두 가지 방법 중 하나를 선택하세요:

방법 1: 환경변수 사용 (권장) ⭐

MCP 클라이언트 설정에서 환경변수로 설정하는 방법입니다. 이 방법을 사용하면 application.yml을 수정할 필요가 없습니다.

장점:

• 설정 파일에 비밀번호를 저장하지 않아도 됩니다

• 여러 환경(개발/운영)에서 다른 설정을 쉽게 사용할 수 있습니다

• application.yml을 수정하지 않아도 되므로 Git에 커밋해도 안전합니다

MCP 클라이언트 설정에서 환경변수를 설정하면 됩니다 (아래 "MCP 클라이언트 연동" 섹션 참조).

방법 2: application.yml 파일 사용

src/main/resources/application.yml 파일을 열어 다음 정보를 수정하세요:

cubrid:
  jdbc:
    # 형식: jdbc:cubrid:<host>:<port>:<db-name>:<user>:<password>:?charSet=utf-8
    # 예시: jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8
    url: jdbc:cubrid:localhost:33000:demodb:dba:your_password:?charSet=utf-8
  user: dba
  password: your_password

JDBC URL 형식 설명:

• host: CUBRID 서버 호스트 주소 (예: localhost, 192.168.1.100)

• port: CUBRID 서버 포트 (기본값: 33000)

• db-name: 데이터베이스 이름 (예: demodb, posart)

• user: 데이터베이스 사용자명 (예: dba)

• password: 데이터베이스 비밀번호

주의: 이 방법을 사용하면 application.yml에 비밀번호가 저장되므로, Git에 커밋하지 않도록 주의하세요.

3. 스키마 설정

CUBRID의 기본 스키마는 보통 dba입니다. 다른 스키마를 사용하는 경우 application.yml에서 수정하거나 환경변수 POLICY_ALLOWED_SCHEMA를 설정하세요:

policy:
  allowed-schema: dba  # 사용할 스키마 이름

또는 환경변수:

export POLICY_ALLOWED_SCHEMA=dba

4. 우선순위

설정 값의 우선순위는 다음과 같습니다:

1. 환경변수 (최우선) - CUBRID_JDBC_URL, CUBRID_USER, CUBRID_PASSWORD

2. application.yml - 환경변수가 없을 때만 사용

중요: MCP 클라이언트 설정에서 환경변수를 설정했다면, application.yml에 같은 정보를 입력할 필요가 없습니다. 환경변수가 우선순위가 높아서 application.yml의 값은 무시됩니다.

5. 환경변수로 설정 (방법 1 사용 시)

MCP 클라이언트 설정에서 환경변수 설정 (권장): MCP 클라이언트 설정 파일의 env 섹션에 환경변수를 설정하면 됩니다. 자세한 내용은 아래 "MCP 클라이언트 연동" 섹션을 참조하세요.

직접 터미널에서 설정 (MCP 클라이언트를 사용하지 않는 경우):

Windows (CMD):

set CUBRID_JDBC_URL=jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8
set CUBRID_USER=dba
set CUBRID_PASSWORD=your_password

Windows (PowerShell):

$env:CUBRID_JDBC_URL="jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8"
$env:CUBRID_USER="dba"
$env:CUBRID_PASSWORD="your_password"

Linux/Mac:

export CUBRID_JDBC_URL="jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8"
export CUBRID_USER="dba"
export CUBRID_PASSWORD="your_password"

📖 사용법

빌드

프로젝트를 빌드하여 JAR 파일을 생성합니다:

mvn clean package

빌드가 완료되면 target/cubrid-mcp-1.0.0-SNAPSHOT.jar 파일이 생성됩니다.

테스트를 건너뛰고 빌드하려면:

mvn clean package -DskipTests

실행

기본 실행

java -jar target/cubrid-mcp-1.0.0-SNAPSHOT.jar

서버는 STDIO 모드로 실행되며:

• stdout: MCP 프로토콜 메시지 (JSON-RPC)

• stderr: 애플리케이션 로그

환경변수와 함께 실행

# Windows
set CUBRID_JDBC_URL=jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8
set CUBRID_USER=dba
set CUBRID_PASSWORD=password
java -jar target/cubrid-mcp-1.0.0-SNAPSHOT.jar

# Linux/Mac
export CUBRID_JDBC_URL="jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8"
export CUBRID_USER="dba"
export CUBRID_PASSWORD="password"
java -jar target/cubrid-mcp-1.0.0-SNAPSHOT.jar

MCP 클라이언트 연동

Claude Desktop 설정

1. Claude Desktop 설정 파일 위치:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. 설정 파일에 다음을 추가:

{
  "mcpServers": {
    "cubrid": {
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "C:/path/to/cubrid-mcp/cubrid-mcp.jar"
      ],
      "env": {
        "CUBRID_JDBC_URL": "jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8",
        "CUBRID_USER": "dba",
        "CUBRID_PASSWORD": "your_password"
      }
    }
  }
}

⚠️ 중요: 경로에 공백이 있는 경우

JAR 파일 경로에 공백이 포함되어 있으면 Java가 파일을 찾지 못할 수 있습니다. 공백이 없는 경로로 JAR 파일을 복사하거나 이동하는 것을 권장합니다.

3. Claude Desktop을 재시작합니다.

Cursor IDE 설정

1. Cursor 설정에서 MCP 서버 추가

2. 설정 파일 경로:

   • Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

   • Mac: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

3. 설정 예시:

{
  "mcpServers": {
    "cubrid": {
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "/absolute/path/to/cubrid-mcp/cubrid-mcp.jar"
      ],
      "env": {
        "CUBRID_JDBC_URL": "jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8",
        "CUBRID_USER": "dba",
        "CUBRID_PASSWORD": "your_password"
      }
    }
  }
}

⚠️ 중요: 경로에 공백이 있는 경우

JAR 파일 경로에 공백이 포함되어 있으면 Java가 파일을 찾지 못할 수 있습니다. 다음 방법 중 하나를 사용하세요:

방법 1: 공백이 없는 경로로 JAR 파일 복사 (권장)

# Windows 예시
copy "target\cubrid-mcp-1.0.0-SNAPSHOT.jar" "C:\cubrid-mcp\cubrid-mcp-1.0.0-SNAPSHOT.jar"

그리고 설정에서:

"args": [
  "-jar",
  "C:/cubrid-mcp/cubrid-mcp-1.0.0-SNAPSHOT.jar"
]

방법 2: args 배열에서 따옴표 사용하지 않기

• ❌ 잘못된 예: "\"D:/path with spaces/file.jar\""

• ✅ 올바른 예: "D:/path with spaces/file.jar"

JSON 배열의 각 요소는 이미 문자열이므로 따옴표를 추가로 이스케이프하면 안 됩니다.

📚 API 문서

Tools

MCP 서버는 다음 4개의 tool을 제공합니다:

1. db.ping

데이터베이스 연결 상태를 확인합니다.

입력: 없음

출력 예시:

{
  "ok": true,
  "serverTime": "2026-01-14T10:55:45.654032300Z",
  "db": "demodb"
}

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "db.ping",
    "arguments": {}
  }
}

2. db.listTables

지정된 스키마의 테이블 목록을 조회합니다.

입력:

• pattern (선택): 테이블명 패턴 (LIKE 패턴, 기본값: "%"

• limit (선택): 최대 반환 개수 (기본값: 500)

출력 예시:

{
  "schema": "dba",
  "tables": [
    {"name": "accept_board_t", "type": "TABLE"},
    {"name": "hbz_admin_t", "type": "TABLE"}
  ]
}

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "db.listTables",
    "arguments": {
      "pattern": "%",
      "limit": 10
    }
  }
}

3. db.describeTable

테이블의 스키마 정보(컬럼, 기본키, 인덱스)를 조회합니다.

입력:

• table (필수): 테이블명 (스키마 없이)

출력 예시:

{
  "schema": "dba",
  "table": "accept_board_t",
  "columns": [
    {
      "name": "bd_seq",
      "type": "NUMERIC(15)",
      "nullable": true
    },
    {
      "name": "company_name",
      "type": "VARCHAR(300)",
      "nullable": true
    }
  ],
  "primaryKey": [],
  "indexes": []
}

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "db.describeTable",
    "arguments": {
      "table": "accept_board_t"
    }
  }
}

4. db.query

SELECT 쿼리를 실행하고 결과를 반환합니다.

입력:

• sql (필수): 실행할 SELECT SQL 쿼리

• maxRows (선택): 최대 행 수 (기본값: 없음, 하드 상한 적용)

• maxBytes (선택): 최대 바이트 수 (기본값: 없음, 하드 상한 적용)

• timeoutMs (선택): 타임아웃 밀리초 (기본값: 없음, 하드 상한 적용)

출력 예시:

{
  "columns": [
    {"name": "bd_seq", "type": "NUMERIC", "nullable": true},
    {"name": "company_name", "type": "VARCHAR", "nullable": true}
  ],
  "rows": [
    [0, "test"],
    [1, "test2"]
  ],
  "rowCount": 2,
  "truncated": false
}

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "db.query",
    "arguments": {
      "sql": "SELECT * FROM dba.accept_board_t",
      "maxRows": 5
    }
  }
}

주의사항:

• SQL 쿼리는 반드시 SELECT로 시작해야 합니다

• 스키마는 dba (또는 설정된 스키마)만 허용됩니다

• LIMIT 절을 SQL에 포함하지 않고 maxRows 파라미터를 사용하는 것을 권장합니다 (CUBRID 호환성)

Resources

MCP 서버는 다음 3개의 resource를 제공합니다:

1. cubrid://schema/summary

스키마의 테이블 요약 정보를 JSON 형식으로 제공합니다.

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": {
    "uri": "cubrid://schema/summary"
  }
}

2. cubrid://schema/dba/{table}

특정 테이블의 스키마 정보를 JSON 형식으로 제공합니다.

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "resources/read",
  "params": {
    "uri": "cubrid://schema/dba/accept_board_t"
  }
}

3. cubrid://docs/policy

서버 정책 문서를 Markdown 형식으로 제공합니다.

사용 예시:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/read",
  "params": {
    "uri": "cubrid://docs/policy"
  }
}

🔒 보안 정책

스키마 제한

• 허용 스키마: 설정 파일의 policy.allowed-schema에 지정된 스키마만 허용 (기본값: dba)

• 다른 스키마 접근 시도는 자동 차단됩니다

SQL 문장 제한

• 허용: SELECT 문만 허용 (WITH 절 포함한 CTE 지원)

• 차단: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE 등 모든 변경/관리 문장

다중 문장 차단

• 세미콜론(;)으로 구분된 다중 SQL 문은 허용되지 않습니다

• 한 번에 하나의 SELECT 문만 실행 가능합니다

결과 제한

하드 상한 (서버 측 강제 제한):

• 최대 행 수: 10,000 행

• 최대 바이트: 20 MB

• 타임아웃: 30 초

Tool 파라미터:

• maxRows, maxBytes, timeoutMs 파라미터로 제한을 설정할 수 있지만, 하드 상한을 초과할 수 없습니다

🧪 테스트

Node.js 테스트 스크립트

프로젝트에 포함된 test-mcp-server.js를 사용하여 MCP 서버를 테스트할 수 있습니다:

1. 테스트 스크립트 수정: test-mcp-server.js 파일을 열어 환경변수를 실제 DB 정보로 수정하세요:

   process.env.CUBRID_JDBC_URL = 'jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8';
   process.env.CUBRID_USER = 'dba';
   process.env.CUBRID_PASSWORD = 'your_password';

2. 테스트 실행:

   node test-mcp-server.js

이 스크립트는 다음을 테스트합니다:

• initialize 메시지 처리

• tools/list - 4개 tool 확인

• resources/list - 3개 resource 확인

• db.ping - DB 연결 테스트

• db.listTables - 테이블 목록 조회

• db.describeTable - 테이블 스키마 조회

• db.query - SELECT 쿼리 실행

Maven 테스트

# 모든 테스트 실행
mvn test

# 특정 테스트 실행
mvn test -Dtest=McpServerIntegrationTest
mvn test -Dtest=ConnectionTest
mvn test -Dtest=McpToolsTest

🔧 문제 해결

연결 오류

문제: Failed to connect to database server

해결 방법:

1. CUBRID 서버가 실행 중인지 확인:

   cubrid server status

2. JDBC URL 형식 확인:

   • 형식: jdbc:cubrid:<host>:<port>:<db-name>:<user>:<password>:?charSet=utf-8

   • 모든 콜론(:)이 올바르게 포함되어 있는지 확인

3. 방화벽 설정 확인:

   • CUBRID 포트(기본값: 33000)가 열려있는지 확인

4. 데이터베이스 이름 확인:

   cubrid listdb

정책 위반 오류

문제: SQL 정책 위반

해결 방법:

• SELECT 문만 사용 가능합니다

• 설정된 스키마(dba)만 허용됩니다

• 다중 문장 사용 불가 (세미콜론으로 구분된 여러 문장)

올바른 예시:

SELECT * FROM dba.accept_board_t
SELECT * FROM dba.accept_board_t WHERE bd_seq = 1

잘못된 예시:

INSERT INTO dba.accept_board_t VALUES (...)
UPDATE dba.accept_board_t SET ...
SELECT * FROM dba.accept_board_t; SELECT * FROM dba.other_table

한글 인코딩 문제

문제: 한글이 깨져서 표시됨

해결 방법:

• JDBC URL에 charSet=utf-8 파라미터가 포함되어 있는지 확인:

  jdbc:cubrid:localhost:33000:demodb:dba:password:?charSet=utf-8

성능 문제

문제: 쿼리 실행이 느림

해결 방법:

1. 하드 상한 설정 확인 (application.yml):

   policy:
     hard-max-rows: 10000
     hard-timeout-ms: 30000

2. 커넥션 풀 크기 조정:

   cubrid:
     pool:
       maximum-pool-size: 10  # 필요시 증가

3. 쿼리 최적화:

   • 필요한 컬럼만 선택

   • WHERE 절 사용

   • 인덱스 활용

🤝 기여하기

버그 리포트, 기능 제안, Pull Request를 환영합니다!

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.

📞 지원

문제가 발생하거나 질문이 있으시면:

• Issues에 등록해주세요

• 또는 이메일로 문의해주세요

Made with ❤️ for the CUBRID community