Skip to main content
Glama
Sign In
deenesjakoruzh
Apache Hive MCP Server

Apache Hive MCP Server

by avelloal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Apache Hive MCP Server

一个针对 Apache Hive（HiveServer2）编写的 MCP 服务器，基于 FastMCP 构建。可以连接任何与 HiveServer2 兼容的端点 — 开源 Apache Hive、Cloudera CDP Base 或 Cloudera CDP Public Cloud（CDW）— 并暴露两个 LLM 智能体可调用的只读工具。

项目摘要

  • 是什么 — 一个 Model Context Protocol 服务器，允许 LLM 智能体查询 Apache Hive：列出表并运行只读 SQL，结果以 JSON 形式返回。

  • 功能对齐 — 与 Cloudera 的 Impala/Iceberg MCP server 一致：相同的 execute_query + get_schema 工具与结构，连接层通过 impyla 切换到 HiveServer2。

  • 在 HiveServer2 支持的所有环境中可用 — 开源 Apache Hive、CDP Base（Kerberos/LDAP）、CDP Public Cloud / CDW（Knox、LDAP over HTTPS）。认证、传输和 TLS 均由 HIVE_* 环境变量驱动。

  • 默认安全 — execute_query 强制执行只读前缀检查（SELECT/SHOW/DESCRIBE/WTH）；写入/DDL 语句将在建立连接前被拒绝。

  • 传输方式 — transstdio（默认）、http 或 sse，通过 MCP_TRANSPORT 选择。

  • 技术栈 — Python ≥3.11、FastMCP、impyla、uv。11 个单元测试（连接层为 mock — 无需真实 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 TABLES，并将表列表以字符串数组组成的 JSON 数组返回。

配置

所有配置均通过环境变量（或项目根目录下的 .env 文件）完成。

变量

默认值

描述

HIVE_HOST

localhost

HiveServer2 主机名或 IP

HIVE_PORT

10000

HiveServer2 thrift 端口

HIVE_ATABASE

default

要连接的数据库

HIVE_USER

（空）

用户名（使用 NOSASL/Kerberos 用例时留空）

HIVE_PASSWORD

（空）

密码（与 PLAIN/LDAP 一起使用）

HIVE_AUTH_MECHANISM

PLAIN

认证方式：NOSASL、PLAIN、LDAP、GSSAPI

HIVE_USE_HTTP_TRANSPORT

false

使用 HTTP 传输而非二进制 thrift

HIVE_HTTP_PATH

cliservice

当 HIVE_USE_HTTP_TRANSPORT=true 时的 HTTP 路径

HIVE_USE_SSL

false

为 thrift 连接启用 TLS

HIVE_KERBEROS_SERVICE_NAME

hive2

Kerberos 服务主体名称（仅限 GSSAPI）

HCP_TRANSPORT

trans

MCP 传输方式：trans（默认）、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 虚拟仓库）

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

启动服务器前，请先通过 kinit 获取 Kerberos 票据。

运行

# 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

  1. 使用上方本地配置 .env。

  2. 启动服务器：

uv run hive-mcp-server

  1. 在第二个终端中，使用 fastmcp 开发检查器或任何 MCP 客户端调用两个工具：

    • get_schema() — 应返回 [] 或表名列表。

    • execute_query("SHOW DATABASES") — 应返回一个数据库名组成的 JSON 数组。

许可证

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

ActivityNo data
ResponsivenessSyncing

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