Teradata MCP 서버

OAuth 2.1 인증, 다중 인증 메커니즘(TD2, LDAP, Kerberos) 및 대화형 데이터 시각화를 지원하는 Teradata 데이터베이스용 MCP(Model Context Protocol) 서버입니다.

기능

다중 인증 메커니즘 — TD2(기본값), LDAP, Kerberos, Teradata LOGMECH를 통한 JWT
OAuth 2.1 — Keycloak 통합, JWT 검증, 범위(scope) 기반 권한 부여
보호된 리소스 메타데이터 (RFC 9728 준수)
대화형 시각화 — 19가지 차트 유형을 지원하는 ECharts 기반 MCP 앱
연결 복원력 — 지수 백오프(exponential backoff)를 통한 자동 재시도
비차단 I/O — 모든 DB 작업은 asyncio.to_thread()를 통해 실행
도구별 QueryBand — Teradata 워크로드 관리를 위한 감사 추적

도구

쿼리 도구

query — SQL 쿼리를 실행하고 일반 표 형식의 결과를 반환
visualize_query — SQL을 실행하고 MCP 앱을 통해 대화형 ECharts 차트를 렌더링

스키마 도구

list_db — 모든 데이터베이스 나열
list_tables — 데이터베이스 내의 테이블/뷰 나열
show_tables_details — 테이블의 열 이름 및 유형 표시

분석 도구

list_missing_values — NULL 값이 있는 열의 개수
list_negative_values — 음수 값이 있는 열의 개수
list_distinct_values — 열별 고유 범주 개수
standard_deviation — 열의 평균 및 표준 편차

MCP 앱 — 대화형 시각화

visualize_query 도구는 MCP 클라이언트에서 결과를 대화형 차트로 렌더링합니다.

카테고리	차트
막대(Bar)	기본, 그룹형, 누적, 가로, 정렬, 폭포, 둥근, 극좌표
선(Line)	기본, 부드러운, 영역, 누적 영역, 계단
파이(Pie)	파이, 도넛, 로즈 / 나이팅게일
산점도(Scatter)	산점도, 버블
혼합(Mixed)	막대 + 선

빠른 시작

설치

git clone https://github.com/arturborycki/mcp-teradata.git
cd mcp-teradata
uv sync

TD2(표준 인증)로 실행

uv run teradata-mcp "teradatasql://user:password@host/database"

또는 환경 변수를 통해 실행:

export DATABASE_URI="teradatasql://user:password@host/database"
uv run teradata-mcp

구성

Claude Desktop

claude_desktop_config.json에 추가하세요:

TD2 (사용자 이름/비밀번호)

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database"
      }
    }
  }
}

LDAP 인증

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "LDAP",
        "DB_LOGDATA": "authcid=ldap_user password=ldap_password"
      }
    }
  }
}

authcid 형식은 LDAP 디렉터리에 따라 다릅니다:

디렉터리	형식
Active Directory (Simple Bind)	`authcid=user@domain.com`
Active Directory (DIGEST-MD5)	`authcid=DOMAIN\username`
OpenLDAP / Sun DS	`authcid=username`

Kerberos 인증

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "KRB5"
      }
    }
  }
}

OAuth 활성화 구성

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database",
        "OAUTH_ENABLED": "true",
        "KEYCLOAK_URL": "https://your-keycloak.example.com",
        "KEYCLOAK_REALM": "teradata-realm",
        "KEYCLOAK_CLIENT_ID": "teradata-mcp",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "OAUTH_RESOURCE_SERVER_URL": "https://your-mcp-server.example.com"
      }
    }
  }
}

환경 변수

데이터베이스 연결

변수	설명	기본값
`DATABASE_URI`	Teradata 연결 URL (`teradatasql://user:pass@host/db`)	—
`DB_LOGMECH`	인증 메커니즘: `TD2`, `LDAP`, `KRB5`, `TDNEGO`, `JWT`	`TD2`
`DB_LOGDATA`	LDAP/JWT 자격 증명 (예: `authcid=user password=pass`)	—
`DB_SSL_MODE`	TLS 모드: `ALLOW`, `PREFER`, `REQUIRE`, `VERIFY-CA`, `VERIFY-FULL`	—
`DB_ENCRYPT_DATA`	전송 암호화 활성화	`true`

연결 복원력

변수	설명	기본값
`DB_MAX_RETRIES`	최대 재연결 시도 횟수	`3`
`DB_INITIAL_BACKOFF`	초기 백오프 지연 시간 (초)	`1.0`
`DB_MAX_BACKOFF`	최대 백오프 지연 시간 (초)	`30.0`

MCP 전송

변수	설명	기본값
`MCP_TRANSPORT`	전송 방식: `stdio`, `sse`, `streamable-http`	`stdio`
`MCP_HOST`	HTTP 전송을 위한 바인딩 주소	`localhost`
`MCP_PORT`	HTTP 전송을 위한 포트	`8000`
`MCP_PATH`	streamable-http를 위한 경로	`/mcp/`

OAuth 2.1

변수	설명	기본값
`OAUTH_ENABLED`	OAuth 인증 활성화	`false`
`KEYCLOAK_URL`	Keycloak 서버 URL	—
`KEYCLOAK_REALM`	Keycloak 영역 이름	—
`KEYCLOAK_CLIENT_ID`	OAuth 클라이언트 ID	—
`KEYCLOAK_CLIENT_SECRET`	OAuth 클라이언트 비밀번호	—
`OAUTH_RESOURCE_SERVER_URL`	리소스 서버 URL	—
`OAUTH_REQUIRED_SCOPES`	필수 범위 (쉼표로 구분)	—
`OAUTH_VALIDATE_AUDIENCE`	토큰 대상 검증	`true`
`OAUTH_VALIDATE_SCOPES`	토큰 범위 검증	`true`
`OAUTH_REQUIRE_HTTPS`	OAuth URL에 HTTPS 요구	`true`
`CORS_ALLOWED_ORIGINS`	CORS 허용 오리진	`*`

OAuth 범위(Scopes)

범위	설명
`teradata:read`	데이터베이스 리소스 읽기 권한
`teradata:write`	데이터베이스 리소스 쓰기 권한
`teradata:query`	SQL 쿼리 실행 권한
`teradata:admin`	관리자 권한
`teradata:schema`	스키마 관리 작업 권한

전송 호환성

전송	OAuth	검색 엔드포인트	사용 사례
stdio	N/A	N/A	Claude Desktop, CLI 클라이언트
SSE	전체	사용 가능	웹 애플리케이션
Streamable HTTP	전체	사용 가능	API 통합

검색 엔드포인트 (OAuth 활성화 시):

/.well-known/oauth-protected-resource — RFC 9728 메타데이터
/.well-known/mcp-server-info — MCP 기능
/health — 상태 확인

Docker 배포

개발

docker compose up -d

OAuth 사용 시

docker compose -f docker-compose.oauth.yml up -d

빌드

uv build

문제 해결

데이터베이스 연결 문제:

DATABASE_URI 형식 확인: teradatasql://user:pass@host/database
Teradata 서버에 대한 네트워크 연결 확인
LDAP의 경우: DB_LOGMECH=LDAP 및 DB_LOGDATA가 올바르게 설정되었는지 확인
연결 문제는 자동으로 재시도됨 (DB_MAX_RETRIES를 통해 구성 가능)

LDAP 인증 실패:

Teradata 서버의 TDGSS에 LDAP이 구성되어 있는지 확인
authcid 형식이 디렉터리 유형과 일치하는지 확인
비밀번호의 특수 문자 이스케이프 처리 (@ → \@, 공백 → 따옴표 사용)

권한 거부 오류:

사용자에게 필요한 OAuth 범위가 있는지 확인
Keycloak 역할 할당 확인
visualize_query는 teradata:query 범위가 필요함 (teradata:read만으로는 부족)

디버그 로깅:

export LOG_LEVEL=DEBUG
uv run teradata-mcp

라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.

Teradata MCP Server