MCP Databricks Server

데이터브릭스 MCP 서버

이 서버는 Statement Execution API를 사용하여 Databricks에 대한 SQL 쿼리를 실행하는 Model Context Protocol(MCP) 서버입니다. Databricks API를 사용하여 SQL 요청을 수행하여 데이터를 검색할 수 있습니다. 에이전트 모드에서 사용하면 여러 요청을 반복하여 복잡한 작업을 성공적으로 수행할 수 있습니다. Unity Catalog Metadata와 함께 사용하면 더욱 효과적입니다.

특징

• Databricks에서 SQL 쿼리 실행
• 카탈로그에서 사용 가능한 스키마 나열
• 스키마의 테이블 나열
• 테이블 스키마 설명

설정

시스템 요구 사항

• 파이썬 3.10+
• uv 를 통해 설치하려는 경우 설치되어 있는지 확인하세요.

설치

1. 필요한 종속성을 설치하세요:

지엑스피1

또는 uv 사용하는 경우:

2. 환경 변수를 설정하세요.옵션 1: .env 파일 사용(권장)Databricks 자격 증명으로 .env 파일을 만듭니다.
   DATABRICKS_HOST=your-databricks-instance.cloud.databricks.com DATABRICKS_TOKEN=your-databricks-access-token DATABRICKS_SQL_WAREHOUSE_ID=your-sql-warehouse-id
   옵션 2: 환경 변수를 직접 설정
   export DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com" export DATABRICKS_TOKEN="your-databricks-access-token" export DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"

SQL Warehouse ID는 Databricks UI의 SQL Warehouse에서 찾을 수 있습니다.

권한 요구 사항

이 MCP 서버를 사용하기 전에 다음 사항을 확인하세요.

1. SQL Warehouse 권한 : 제공된 토큰과 연결된 사용자는 지정된 SQL Warehouse에 액세스할 수 있는 적절한 권한이 있어야 합니다. Databricks UI의 SQL Warehouse > [내 Warehouse] > 권한에서 웨어하우스 권한을 구성할 수 있습니다.
2. 토큰 권한 : 사용되는 개인 액세스 토큰은 필요한 작업을 수행하는 데 필요한 최소한의 권한을 가져야 합니다. 다음 사항을 강력히 권장합니다.
   • 이 애플리케이션에 대한 전용 토큰을 생성하세요
   • 가능한 경우 보안 위험을 제한하기 위해 읽기 전용 권한을 부여하세요.
   • 작업 공간 전체 관리자 권한이 있는 토큰을 사용하지 마세요.
3. 데이터 액세스 권한 : 토큰과 연결된 사용자는 쿼리될 카탈로그, 스키마 및 테이블에 액세스하기 위한 적절한 권한이 있어야 합니다.

Databricks REST API를 통해 SQL Warehouse 권한을 설정하려면 다음을 사용할 수 있습니다.

• 현재 권한을 확인하려면 GET /api/2.0/sql/permissions/warehouses/{warehouse_id}
• PATCH /api/2.0/sql/permissions/warehouses/{warehouse_id} 권한을 업데이트합니다.

보안 모범 사례를 위해 액세스 토큰을 정기적으로 교체하고 쿼리 기록을 감사하여 사용량을 모니터링하는 것을 고려하세요.

서버 실행

독립형 모드

독립 실행형 모드로 서버를 실행하려면:

이렇게 하면 Agent Composer나 다른 MCP 클라이언트와 함께 사용할 수 있는 stdio 전송을 사용하여 MCP 서버가 시작됩니다.

커서와 함께 사용

이 MCP 서버를 Cursor 와 함께 사용하려면 Cursor 설정에서 다음과 같이 구성해야 합니다.

1. 홈 디렉토리에 .cursor 디렉토리가 없으면 새로 만드세요.
2. 해당 디렉토리에 mcp.json 파일을 만들거나 편집하세요.

3. 다음 구성을 mcp.json 파일에 추가하고 디렉토리 경로를 이 서버를 설치한 실제 경로로 바꿉니다.

uv 사용하지 않는 경우 대신 python 사용할 수 있습니다.

4. 변경 사항을 적용하려면 커서를 다시 시작하세요.

이제 Cursor의 AI 어시스턴트 내에서 Databricks MCP 서버를 직접 사용할 수 있습니다.

사용 가능한 도구

서버는 다음과 같은 도구를 제공합니다.

1. execute_sql_query : SQL 쿼리를 실행하고 결과를 반환합니다.
   execute_sql_query(sql: str) -> str
2. list_schemas : 특정 카탈로그에서 사용 가능한 모든 스키마를 나열합니다.
   list_schemas(catalog: str) -> str
3. list_tables : 특정 스키마의 모든 테이블을 나열합니다.
   list_tables(schema: str) -> str
4. describe_table : 테이블의 스키마를 설명합니다.
   describe_table(table_name: str) -> str

사용 예

Agent Composer나 다른 MCP 클라이언트에서는 다음과 같은 도구를 사용할 수 있습니다.

장기 실행 쿼리 처리

이 서버는 쿼리가 완료되거나 시간 초과될 때까지 Databricks API를 폴링하여 장기 실행 쿼리를 처리하도록 설계되었습니다. 기본 시간 초과는 10분(10초 간격으로 60회 재시도)이며, 필요한 경우 dbapi.py 파일에서 조정할 수 있습니다.

종속성

• httpx: Databricks API에 HTTP 요청을 하기 위해
• python-dotenv: .env 파일에서 환경 변수를 로드하기 위해
• mcp: 모델 컨텍스트 프로토콜 라이브러리
• asyncio: 비동기 작업용