소개

이 문서에서는 모델 컨텍스트 프로토콜(MCP)용 일반 ODBC 서버( mcp-odbc 서버)의 설정 및 사용에 대해 설명합니다. 이 서버는 특정 ODBC 커넥터(ODBC 드라이버라고도 함)에 대해 구성된 데이터 소스 이름을 통해 대규모 언어 모델(Large Language Model)이 ODBC 액세스 가능 데이터 소스에 투명하게 액세스할 수 있도록 개발되었습니다.

서버 구현

ODBC용 MCP 서버 는 node-odbc 위에 구축된 작은 TypeScript 계층입니다. node.js (TypeScript용 npx 사용)를 통해 호스트 시스템의 로컬 ODBC 드라이버 관리자로 호출을 라우팅합니다.

운영 환경 설정 및 전제 조건

다음 예제는 Virtuoso ODBC 커넥터를 기준으로 작성되었지만, 이 가이드에서는 다른 ODBC 커넥터도 사용할 수 있습니다. 이 프로젝트에 통합하기 위해 다른 데이터베이스 관리 시스템(DBMS) 관련 코드 기여 및 사용 데모 제출을 적극 권장합니다.

주요 시스템 구성 요소

1. node.js 버전을 확인하세요. 21.1.0 이상이 아니면 다음 명령어를 사용하여 업그레이드하거나 설치하세요.

   지엑스피1

2. 다음을 사용하여 MCP 구성 요소를 설치합니다.

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

3. 다음을 사용하여 nvm 버전을 설정합니다.

   nvm alias default 21.1.0

설치

1. 달리다

   git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git

2. 디렉토리 변경

   cd mcp-odbc-server

3. 달리다

   npm init -y

4. 달리다

   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

unixODBC 런타임 환경 검사

1. 다음을 실행하여 설치 구성(즉, 주요 INI 파일의 위치)을 확인하세요.

   odbcinst -j

2. 다음을 실행하여 사용 가능한 데이터 소스 이름(DSN)을 나열합니다.

   odbcinst -q -s

환경 변수

좋은 보안 관행으로, mcp-ser 와 같은 디렉토리에 있는 .env 파일을 사용하여 ODBC 데이터 원본 이름( ODBC_DSN ), 사용자( ODBC_USER ), 비밀번호( ODBC_PWD ), ODBC INI( ODBCINI )에 대한 바인딩을 설정하고, ODBC를 통해 OPAL(OpenLink AI Layer)을 사용하려는 경우 대상 LLM(Large Language Model) API 키( API_KEY )도 설정해야 합니다.

용법

도구

성공적으로 설치하면 MCP 클라이언트 애플리케이션에서 다음 도구를 사용할 수 있습니다.

개요

자세한 설명

• get_schemas

  • 연결된 데이터베이스에서 모든 스키마 이름 목록을 검색하여 반환합니다.

  • 입력 매개변수:

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 스키마 이름의 JSON 문자열 배열을 반환합니다.

• get_tables

  • 지정된 스키마의 테이블 정보가 포함된 목록을 검색하여 반환합니다. 스키마가 제공되지 않으면 연결의 기본 스키마를 사용합니다.

  • 입력 매개변수:

    • schema (문자열, 선택 사항): 테이블을 필터링할 데이터베이스 스키마입니다. 기본값은 연결 기본값입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 테이블 정보(예: TABLE_CAT , TABLE_SCHEM , TABLE_NAME , TABLE_TYPE )를 포함하는 JSON 문자열을 반환합니다.

• filter_table_names

  • 이름에 특정 하위 문자열이 포함된 테이블에 대한 정보를 필터링하고 반환합니다.

  • 입력 매개변수:

    • q (문자열, 필수): 테이블 이름 내에서 검색할 하위 문자열입니다.

    • schema (문자열, 선택 사항): 테이블을 필터링할 데이터베이스 스키마입니다. 기본값은 연결 기본값입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 일치하는 테이블에 대한 정보가 포함된 JSON 문자열을 반환합니다.

• describe_table

  • 특정 테이블의 열에 대한 자세한 정보를 검색하여 반환합니다.

  • 입력 매개변수:

    • schema (문자열, 필수): 테이블이 포함된 데이터베이스 스키마 이름입니다.

    • table (문자열, 필수): 설명할 테이블의 이름입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 테이블의 열(예: COLUMN_NAME , TYPE_NAME , COLUMN_SIZE , IS_NULLABLE )을 설명하는 JSON 문자열을 반환합니다.

• query_database

  • 표준 SQL 쿼리를 실행하고 결과를 JSON 형식으로 반환합니다.

  • 입력 매개변수:

    • query (문자열, 필수): 실행할 SQL 쿼리 문자열입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 쿼리 결과를 JSON 문자열로 반환합니다.

• query_database_md

  • 표준 SQL 쿼리를 실행하고 마크다운 테이블 형식으로 결과를 반환합니다.

  • 입력 매개변수:

    • query (문자열, 필수): 실행할 SQL 쿼리 문자열입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 쿼리 결과를 마크다운 테이블 문자열로 반환합니다.

• query_database_jsonl

  • 표준 SQL 쿼리를 실행하고 JSON Lines(JSONL) 형식으로 결과를 반환합니다(줄당 JSON 개체 하나).

  • 입력 매개변수:

    • query (문자열, 필수): 실행할 SQL 쿼리 문자열입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 쿼리 결과를 JSONL 문자열로 반환합니다.

• spasql_query

  • SPASQL(SQL/SPARQL 하이브리드) 쿼리를 실행하여 결과를 반환합니다. 이는 Virtuoso 전용 기능입니다.

  • 입력 매개변수:

    • query (문자열, 필수): SPASQL 쿼리 문자열입니다.

    • max_rows (숫자, 선택 사항): 반환할 최대 행 수입니다. 기본값은 20 입니다.

    • timeout (숫자, 선택 사항): 쿼리 시간 초과(밀리초). 기본값은 30000 , 즉 30초입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 기본 저장 프로시저 호출(예: Demo.demo.execute_spasql_query )의 결과를 반환합니다.

• sparql_query

  • SPARQL 쿼리를 실행하고 결과를 반환합니다. 이는 Virtuoso 전용 기능입니다.

  • 입력 매개변수:

    • query (문자열, 필수): SPARQL 쿼리 문자열.

    • format (문자열, 선택 사항): 원하는 결과 형식입니다. 기본값은 'json' 입니다.

    • timeout (숫자, 선택 사항): 쿼리 시간 초과(밀리초). 기본값은 30000 , 즉 30초입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • 기본 함수 호출(예: "UB".dba."sparqlQuery" )의 결과를 반환합니다.

• virtuoso_support_ai

  • Virtuoso 전용 AI 어시스턴트 기능을 활용하여 프롬프트와 선택적 API 키를 전달합니다. 이는 Virtuoso 전용 기능입니다.

  • 입력 매개변수:

    • prompt (문자열, 필수): AI 함수에 대한 프롬프트 텍스트입니다.

    • api_key (문자열, 선택 사항): AI 서비스의 API 키입니다. 기본값은 "none" 입니다.

    • user (문자열, 선택 사항): 데이터베이스 사용자 이름입니다. 기본값은 "demo" 입니다.

    • password (문자열, 선택 사항): 데이터베이스 비밀번호입니다. 기본값은 "demo" 입니다.

    • dsn (문자열, 선택 사항): ODBC 데이터 원본 이름입니다. 기본값은 "Local Virtuoso" 입니다.

  • AI Support Assistant 함수 호출(예: DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI )의 결과를 반환합니다.

기본 설치 테스트 및 문제 해결

MCP 검사 도구

Canonical MCP Inspector 도구 에디션

1. 다음 명령을 사용하여 mcp-server 디렉토리/폴더에서 검사기를 시작합니다.

   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts

2. "연결" 버튼을 클릭한 다음 "도구" 탭을 클릭하여 시작하세요.

   

OpenLink MCP Inspector 도구 에디션

이는 MCP 서버와 함께 사용하는 것과 관련된 JSON 처리 버그 수정을 포함하는 정식 버전의 포크입니다.

1. 달리다

   git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector

2. 달리다

   npm run start

3. http://localhost:6274 에서 MCP Inspectors UI의 Arguments 입력 필드에 다음 값을 제공하세요.

   tsx /path/to/mcp-odbc-server/src/main.ts

4. 지정된 MCP 서버와의 세션을 초기화하려면 Connect 버튼을 클릭하세요.

Apple Silicon(ARM64)과 MCP ODBC 서버 간의 호환성 문제

Node x86_64 vs arm64 충돌 문제

node 의 arm64 버전이 아닌 x86_64 버전이 있을 수 있지만, ODBC 브리지와 MCP 서버는 arm64 기반 구성 요소입니다.

다음 단계를 수행하면 이 문제를 해결할 수 있습니다.

1. 다음을 실행하여 node 의 x86_64 에디션을 제거합니다.

   nvm uninstall 21.1.0

2. 다음 명령을 실행하여 현재 셸이 arm64 모드인지 확인하세요.

   arch

   • x86_64가 반환되면 다음 명령을 실행하여 활성 모드를 변경하세요.

     arch arm64

3. 다음을 실행하여 node 의 arm64 에디션을 설치하세요.

   nvm install 21.1.0

ODBC 브리지 계층 비호환성 노드

Apple Silicon 컴퓨터에서 MCP(Model Context Protocol) ODBC 서버를 사용하려고 할 때 아키텍처 불일치 오류가 발생할 수 있습니다. 이는 Node.js ODBC 네이티브 모듈( odbc.node )이 ARM64 아키텍처용으로 컴파일되었지만, unixODBC 런타임의 x86_64 기반 버전이 로드되기 때문에 발생합니다.

일반적인 오류 메시지:

다음 단계를 수행하여 이 문제를 해결하세요.

1. Node.js가 ARM64 모드에서 실행 중인지 확인하세요.

   node -p "process.arch" # Should output: `arm64`

2. ARM64용 unixODBC를 설치하세요:

   # Verify Homebrew is running in ARM64 mode which brew # Should point to /opt/homebrew/bin/brew # Remove existing unixODBC brew uninstall --force unixodbc # Install ARM64 version arch -arm64 brew install unixodbc

3. ARM64용 Node.js ODBC 모듈을 다시 빌드합니다.

   # Navigate to your project cd /path/to/mcp-odbc-server # Remove existing module rm -rf node_modules/odbc # Set architecture environment variable export npm_config_arch=arm64 # Reinstall with force build npm install odbc --build-from-source

4. 모듈이 이제 ARM64인지 확인하세요.

   file node_modules/odbc/lib/bindings/napi-v8/odbc.node # Should show "arm64" instead of "x86_64"

핵심 포인트

• unixODBC와 Node.js ODBC 모듈은 모두 ARM64와 호환되어야 합니다.

• 환경 변수 사용( export npm_config_arch=arm64 )은 npm config 명령보다 더 안정적입니다.

• 항상 file 명령이나 node -p "process.arch" 사용하여 아키텍처를 확인하세요.

• Apple Silicon에서 Homebrew를 사용할 때 명령 앞에 arch -arm64 붙여 ARM64 바이너리를 강제로 사용할 수 있습니다.

MCP 애플리케이션 사용

클로드 데스크톱 구성

이 구성 파일의 경로는 ~{username}/Library/Application Support/Claude/claude_desktop_config.json 입니다.

클로드 데스크톱 사용법

1. 애플리케이션을 시작합니다.

2. 설정 | 개발자 사용자 인터페이스를 통해 구성을 적용합니다(위에서).

3. DSN(데이터 원본 이름)에 대한 ODBC 연결이 작동하는지 확인하세요.

4. 쿼리 실행을 요청하는 프롬프트를 제시합니다. 예:

   Execute the following query: SELECT TOP * from Demo..Customers

   

Cline(Visual Studio Extension) 구성

이 구성 파일의 경로는 다음과 같습니다. ~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Cline(Visual Studio Extension) 사용법

1. Shift+Command+P를 사용하여 명령 팔레트를 엽니다.

2. 입력: Cline .

3. 선택: VSCode 사이드바에 Cline UI를 여는 Cline View.

4. MCP 서버를 설치하고 구성하기 위한 UI에 접근하려면 네 개의 사각형 아이콘을 사용하세요.

5. 위의 Cline Config를 적용합니다.

6. 확장 프로그램의 기본 UI로 돌아가서 다음 프롬프트 처리를 요청하는 새 작업을 시작합니다.

   "Execute the following query: SELECT TOP 5 * from Demo..Customers"

   

커서 구성

설정 기어를 사용하여 mcp servers 등록하고 구성하기 위한 MCP 메뉴 항목이 포함된 구성 메뉴를 엽니다.

커서 사용

1. 채팅 인터페이스를 열려면 Command + I 또는 Control + I 키 조합을 사용하세요.

2. UI 왼쪽 하단의 드롭다운에서 Agent 선택합니다. 기본값은 Ask 입니다.

3. @odbc {rest-of-prompt} 패턴을 사용하여 mcp-server for odbc 사용을 인증하는 프롬프트를 입력합니다.

4. 프롬프트를 실행하려면 "수락"을 클릭하세요.

   

관련된

• MCP 검사기 사용 스크린캐스트

• 기본 Claude 데스크톱 사용법 스크린캐스트

• 기본 Cline Visual Studio Code 확장 프로그램 사용법 스크린캐스트

• 기본 커서 편집기 사용법 스크린캐스트