Skip to main content
Glama
deenesjakoruzh
avelloal

Apache Hive MCP Server

by avelloal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Apache Hive MCP Server

Apache Hive(HiveServer2)용 MCP 서버로, FastMCP로 구축되었습니다. 오소스 Apache Hive, Cloudera CDPlela CDP Base, Cloudera CDP Public Cloud(CDW) 등 HiveServer2호환 엔드포인트에 무엇이든 연결할 수 있으며, LLM 에이전트가 호출할 수 있는 두 가지 N기 전용 도구를 노출합니다.

프로젝트 요약

  • 정의 — LLM 에이전트가 Apache Hive를 리할 수 있는 Model Context Protocol 서버입니다: 테이블을 읽 조회하고 N기 전용 SQL를 실행하며, 결과과는 JSON로 반환됩니다.

  • 기능 동등성 — Cloudera의 [Impala/Iceberg MCP server|https://github.com/cloudera/ceberg-mcP-server)|동일한 execute_query + get_schema 도구와 구조를 가지며, 연결 계층은[impyla|https://github.com/cloudera/impyla)를 통해 HiveServer2로 교체되었습니다.

  • HiveServer2가 지원되되는 모든 곳에서 동작 — 오소스 Apache Hive(, CDP Base(Kerberos/LDAP), CDP Public Cloud / CDW(, Knox, HTTPS LDAP 등. 인증, 전송, TLS Db는 모두 HIVE_* 환경변홖로 제어됩니다.

  • 기본적으로 안전 — execute_query는 읽기 전용 접두 고드(SELECT/SHOW/DESCRIBE/WITH)를 적용하며, 쓰기/DDL 문은 연결 전에 거부됩니다.

  • 전송 방식 — stdio(기본값), http, sse 중 선택하며, MCP_TRANSPORT로 지정합니다.

  • 기술 스택 — Python ≥3.10, FastMCP, impyla, uv. 단위 테스트 11개(연결은 목업 처리 — 라이브 Hive 불필요).

Related MCP server: impala-mcp-server

도구

도구

시그니쳐

설명

execute_query

execute_query(query: str) -> str

읽기 전용 SQL 쿼리(SELECT, SHOW, DESCRIBE¶, WITH)를 실행하고 결과를 컬럼 키 객체의 JSON 배열로 반환합니다. 쓰기 작업은 오류 문자열과 함께 거부됩니다.

get_schema

get_schema() -> str

기본 데이터베이스에서 SHOW TABLESES를 실행하고 테이블 이름 목록을 JSON 문자열 배열로 반환합니다.

구성

모든 구성은 환경 변수(또는 프로젝트 루트의 .env 파일)로 지정합니다.

변수

기본값

설명

HIVE_HOST

localhost

HiveServer2 호스트 이름 또는 IP

HIVE_PORT

10000

HiveServer2 Thrift 포트

HIVE_DATABASE

default

연결할 데이터베이스

HIVE_USER

(비어 있음)

사용자 이름(NOSASL/Kerberos에서는 비워 둠)

HIVE_PASSWORD

(비어 있음)

비밀번호(PLAIN/LDAP에서 사용)

HIVE_AUTH_MECHANISM

PLAIN

인증 방식: NOSASL, PLAIN, LDAP, GSSAPI

HIVE_USE_HTTP_TRANSPORT

false

바이너리 Thrift 대신 HTTP 전송 사용

HIVE_HTTP_PATH

cliservice

HIVE_USE_HTTP_TRANSPORT=true일 때의 HTTP 경로

HIVE_USE_SSL

false

Thrift 연결에 TLS 활성화

HIVE_KERBEROS_SERVICE_NAME

hive

Kerberos 서비스 프린시펄 이름(GSSAPI 전용)

MCP_TRANSPORT

stdio

MCP 전송: stdio, http 또는 sse

.env.example을 .env로 복사한 후 값을 입력하세요.

배포 프리셋

로컬 / 개발(Docker HiveServer2)

HIVE_HOST=localhost
HIVE_PORT=10000
HIVE_DATABASE=default
HIVE_AUTH_MECHANISM=NOSASL
MCP_TRANSPORT=stdio

CDP Public Cloud(CDW 가상 웨어하우스)

CDP Public Cloud(CDW Virtual Warehouse)

HIVE_HOST=<coordinator-hostname>.dw.cloudera.site
HIVE_PORT=443
HIVE_DATABASE=default
HIVE_USER=<workload-username>
HIVE_PASSWORD=<workload-password>
HIVE_AUTH_MECHANISM=LDAP
HIVE_USE_HTTP_TRANSPORT=true
HIVE_HTTP_PATH=cliservice
HIVE_USE_SSL=true
MCP_TRANSPORT=stdio

CDP Base / 온프레미스(Kerberos)

HIVE_HOST=<hiveserver2-host.example.com>
HIVE_PORT=10000
HIVE_DATABASE=default
HIVE_AUTH_MECHANISM=GSSAPI
HIVE_KERBEROS_SERVICE_NAME=hive
MCP_TRANSPORT=stdio

서버를 시작하기 전에 Kerberos 티켓(kinit)을 발급받으세요.

실행

# Install
pip install -e .
# or with uv:
uv sync

# Copy and edit config
cp .env.example .env

# Start (stdio transport, for use with an MCP host)
uv run hive-mcp-server

MCP 클라이언트 구성

MCP 호스트(Claude Desktop, Cloudera AI Agent Studio 등)는 mcpServers JSON 블록으로 서버를 등록합니다. uvx는 이 서버를 GitHub에서 직접 실행합니다 — 로컬 설치나 PyPI 배포가 필요 없습니다. 환경에 맞게 HIVE_* 값을 채우세요(구성 및 위 프리셋 참조).

{
    "mcpServers": {
        "Hive": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/avelloal/hive-mcp-server@v0.1.0",
                "hive-mcp-server"
            ],
            "env": {
                "HIVE_HOST": "<coordinator-hostname>.dw.cloudera.site",
                "HIVE_PORT": "443",
                "HIVE_DATABASE": "default",
                "HIVE_USER": "<workload-username>",
                "HIVE_PASSWORD": "<workload-password>",
                "HIVE_AUTH_MECHANISM": "LDAP",
                "HIVE_USE_HTTP_TRANSPORT": "true",
                "HIVE_HTTP_PATH": "cliservice",
                "HIVE_USE_SSL": "true"
            }
        }
    }
}

위 예제는 CDP Public Cloud / CDW를 대상으로 합니다. 로컬 또는 Kerberos 타겟의 경우 위 프리셋을 사용하여 env 값만 바꾸면 됩니다. @v0.1.0은 특정 릴리스를 고정합니다 — 제거하면 최신 버전을 추적하고, 더 새 버전으로 올릴 수도 있습니다.

Cloudera AI Agent Studio의 경우(등록 절차, 환경 변수 처리, stdio/uvx 제약 사항)에는 examples/agent-studio/를 참조하세요.

스모크 테스트

  1. 로컬 HiveServer2 시작(예: Apache Hive Docker 이미지):

    docker run -d -p 10000:10000 apache/hive:3.1.3

  2. 위 로컬 프리셋으로 .env을 구성합니다.

  3. 서버 시작:

    uv run hive-mcp-server

  4. 두 번째 터미널에서 fastmcp 개발 인스펙터 또는 아무 MCP 클라이언트로 두 도구를 호출해 보세요:

    • get_schema() — [] 또는 테이블 이름 목록을 반환해야 합니다.

    • execute_query("SHOW DATABASES") — 데이터베이스 목록의 콸 JSON 배열을 반환해야 합니다.

라이선

라이선스

Apache License 2 — LICENSE를 참조하세요.

라이선스

Apache License 2.0 — LICENSE를 참조하세요.

라이선스

Apache License 2.0 — LICENSE를 참조하세요.

Available Tools

2 tools
execute_queryA

Execute a read-only SQL query on Hive and return results as JSON.

NameRequiredDescriptionDefault
queryYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that the tool is read-only and returns JSON, which are meaningful safety and output traits. However, it doesn't explain error behavior, query size limits, permission expectations, or how results are shaped.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the action, target, and output format. There is no wasted or redundant phrasing; every clause adds information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema present, the description covers the essential usage context: the action, the data source, the read-only safety property, and the return format. It could add routing to get_schema, but the core invocation context is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter semantics. 'SQL query on Hive' clarifies that the query parameter should be a Hive SQL string, which adds meaning beyond the schema's bare 'query' field. But the description never mentions the parameter by name or provides syntax, limits, or examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Execute') and resource ('SQL query on Hive'), and also names the output format ('results as JSON'). It clearly distinguishes this tool from the sibling get_schema, which is about schema retrieval rather than running queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance about when to use this tool versus get_schema, or when not to use it. The 'read-only' qualifier is a constraint, but it doesn't describe alternatives or usage scenarios beyond what the description literally states.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_schemaA

List the table names in the current Hive database.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the disclosure burden. It communicates a read-only, list-style behavior and the scope to the current Hive database, but it does not mention return format, potential limitations, or side effects. For such a simple zero-parameter read operation, this is adequate but not richly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single-front-loaded sentence communicates the core action and target resource with no superfluous words. Every part of the description adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no parameters and an output schema is provided, so the description only needs to specify what is listed and in what context. The single sentence fully covers that for a minimal introspection operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter count is 0, so there is no semantic burden on the description. The description accurately describes what the tool will produce, and no parameter-related information is required beyond the schema's empty object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List'), identifies the exact resource ('table names'), and scopes it to the 'current Hive database.' This clearly distinguishes it from the sibling tool execute_query, which focuses on running queries rather than returning schema metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the tool's purpose obvious: use it when you need the list of table names in the current Hive database. However, it does not explicitly contrast this with execute_query or state when to prefer one over the other, leaving the routing decision somewhat implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedexecute_query
    • First observedget_schema
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one executes SQL queries, the other lists table names. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent snake_case verb_noun pattern: execute_query and get_schema. The naming is predictable and easy to extend.

Tool Count3/5

Two tools is on the thin side for a full Apache Hive server, though the set is minimal and comprehensible. It feels borderline but not absurdly incomplete.

Completeness3/5

The set covers basic querying and table listing, but lacks explicit schema/column detail, database selection, and non-query operations. An agent can partially work around this via execute_query, but there are notable gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Cloudera Hive MCP Server

    manojjain10
    F
    license
    A
    quality
    D
    maintenance
    Enables LLM agents to query and explore Cloudera Hive virtual warehouses through tools like list_databases, list_tables, describe_table, get_table_sample, and execute_query with read-only safety.
    5
    -

  • impala-mcp-server

    yaowenqiang
    A
    license
    A
    quality
    C
    maintenance
    Enables AI agents to safely query and explore Apache Impala clusters with read-only SQL, metadata, statistics, cluster overview, and analysis prompt templates.
    17
    Apache 2.0