使用说明

云时代经理mcp

用于Cloudera Manager REST API的MCP（模型上下文协议）服务器。为运行在上的多代理日志分析和操作平台而设计 Cloudera公共云/CDP。

服务器将CM功能作为MCP工具公开，以便内置代理 Cloudera代理工作室 可以提取日志、检索警报、读取和修改配置、重启服务和管理CM注册表——全程一个单一、一致的界面。

建筑

Cloudera Agent Studio
        │
        │  MCP (stdio)
        ▼
┌─────────────────────────┐
│   cloudera-manager-mcp  │
│                         │
│  server.py              │  tool dispatch
│  ├── cm_pool.py         │  HTTP client pool (one per CM)
│  ├── cm_client.py       │  CM REST API calls (httpx + tenacity)
│  ├── cm_registry.py     │  Iceberg registry via Impala / HiveServer2
│  ├── config.py          │  settings from environment variables
│  └── models.py          │  Pydantic I/O models
└────────────┬────────────┘
             │  HTTPS / REST API
             ▼
   Cloudera Manager instances
   (one per DataHub environment)
             │
             │  reads / writes
             ▼
   Iceberg table — cdp_registry.cloudera_managers
   (Impala or HiveServer2)

CM实例是不在环境变量中配置。它们被存放在冰山表中，并在启动时装载。中的唯一变量 .env 是Impala/HiveServer2连接读取该表所需的参数。

项目结构

cloudera-mcp-server/
├── pyproject.toml                       package metadata, dependencies, entry point
├── env.example                          environment variable template
├── agent_studio_mcp.json                Agent Studio MCP server configuration
├── requirements.txt                     pip-compatible dependency list
├── docs/
│   └── registry_table.sql               DDL for the Iceberg registry table
└── src/
    └── cloudera_manager_mcp/
        ├── __init__.py
        ├── server.py                    MCP server entry point, tool definitions and dispatch
        ├── cm_client.py                 async HTTP client for CM REST API
        ├── cm_pool.py                   multi-CM connection pool, cluster → host resolution
        ├── cm_registry.py               Iceberg registry (Impala / HiveServer2 via impyla)
        └── config.py                    Pydantic settings (ImpalaSettings, ServerSettings)

先决条件

要求	版本
Python 3.11或更高版本
uv	0.4或更高-- 安装
Cloudera Manager	7.x（CDP 7.1.7+）
Impala或HiveServer2	支持Iceberg v2的任何版本
CM用户角色	群集管理员或更高级别

安装

# Clone the repository
git clone https://github.com/dvergari/cloudera-mcp-server.git
cd cloudera-mcp-server

# Create the virtual environment and install all dependencies
uv sync

# Copy and edit the environment configuration
cp env.example .env
$EDITOR .env

uv sync 读取 pyproject.toml，解析依赖关系图，创建 .venv/ 在项目根目录中，并安装所有内容。无手册 pip install 需要一步。

配置

所有配置都是通过环境变量完成的，从加载 .env 在启动时。看 .env.example 以获取内联文档的完整参考。

可变组

前缀	目的
`MCP_*`	服务器行为——日志级别、并发限制、重试策略
`IMPALA_*`	CM注册表Iceberg表的SQL后端

SQL后端选择

服务器支持两个后端用于读取冰山注册表，两者均通过 impyla:

`IMPALA_BACKEND`	默认端口	Kerberos服务
`impala`	21050	`impala`
`hiveserver2`	10000	`hive`

设置 IMPALA_BACKEND=hiveserver2 足以切换后端。端口和Kerberos服务名称将从以下位置自动解析后端，除非明确覆盖。

最小化 `.env` 用于开发（Impala，无TLS）

MCP_LOG_LEVEL=DEBUG
IMPALA_BACKEND=impala
IMPALA_HOST=impala-dev.example.com
IMPALA_AUTH_MECHANISM=PLAIN
IMPALA_USE_SSL=false
IMPALA_DATABASE=cdp_registry
IMPALA_TABLE=cloudera_managers

最小化 `.env` 用于生产（HiveServer2、LDAP、TLS）

MCP_LOG_LEVEL=INFO
IMPALA_BACKEND=hiveserver2
IMPALA_HOST=hs2-prod.example.com
IMPALA_AUTH_MECHANISM=LDAP
IMPALA_USERNAME=svc-mcp-agent
IMPALA_PASSWORD=<password>
IMPALA_USE_SSL=true
IMPALA_DATABASE=cdp_registry
IMPALA_TABLE=cloudera_managers
IMPALA_REFRESH_INTERVAL_SECS=300

在本地运行

# Run directly with uv (recommended)
uv run cloudera-manager-mcp

# Or activate the virtualenv first
source .venv/bin/activate
cloudera-manager-mcp

服务器启动并监听标准（标准输入/输出）

Cloudera Agent Studio中的部署

这 agent_studio_mcp.json 文件包含即用型配置块针对三种部署模式。将相关块复制到Agent Studio中→ 设置→ MCP服务器.

模式A——本地结账（开发）

用途 uv --directory 在适当的位置运行服务器。无需构建步骤；uv自动管理virtualenv。

{
  "command": "uv",
  "args": [
    "--directory", "/path/to/cloudera-mcp-server-en",
    "run", "cloudera-manager-mcp"
  ],
  "env": { "IMPALA_HOST": "...", "..." : "..." }
}

模式B——Git存储库（暂存/CI）

用途 uvx --from git+https://... 只需一步即可安装和运行。将URL替换为您的内部GitLab或GitHub存储库。

{
  "command": "uvx",
  "args": [
    "--from", "git+https://github.com/dvergari/cloudera-mcp-server.git",
    "cloudera-manager-mcp"
  ],
  "env": { "IMPALA_HOST": "...", "..." : "..." }
}

模式C——本地车轮（气隙/生产）

构建一次轮子，将其复制到路径中的Agent Studio主机 /home/cdsw/agent-studio/.local/share/mcp，然后点 uvx 在沙盒路径上。运行时不需要网络访问。

# Build
uv build
# → dist/cloudera_manager_mcp-1.0.0-py3-none-any.whl

# Copy to the Agent Studio host, then configure:

{
  "command": "uvx",
  "args": [
    "--from", "/home/cdsw/.local/share/uv/mcp/cloudera_manager_mcp-1.0.0-py3-none-any.whl",
    "cloudera-manager-mcp"
  ],
  "env": { "IMPALA_HOST": "...", "..." : "..." }
}

外露工具

CM操作工具

工具	说明
`get_service_logs`	使用主机、角色类型、日志级别和关键字过滤器从服务（YARN、HDFS、Solr、Spark、Hive……）中提取日志
`get_alerts`	获取按集群、严重性、服务和时间范围过滤的CM健康警报
`get_service_metrics`	使用CM度量名称检索时间序列度量（cpu_percent、jvm_heap_used_mb…）
`get_config`	读取服务或角色配置组配置； `view=full` 包括默认值
`update_config`	修改单个CM配置参数；总是回来 `old_value` 用于验证
`run_service_command`	启动/停止/重新启动/滚动重新启动服务--异步，返回 `command_id`
`get_command_status`	通过以下方式轮询正在运行的CM命令的状态 `command_id`
`get_host_status`	群集主机的运行状况：运行状况摘要、资源、活动角色
`get_audit_events`	CM审核日志条目：登录、配置更改、服务操作
`list_datahubs`	枚举DataHub集群，包括状态、服务、节点计数、云提供商
`list_clusters`	列出每个配置的CM实例管理的所有集群
`list_services`	列出特定集群中的服务
`refresh_cluster_map`	重建内部群集→ CM主机查找表

注册表管理工具

工具	说明
`registry_list`	列出冰山表中存储的所有CM实例（密码除外）
`registry_stats`	汇总统计数据：总CM、活动计数、环境、云提供商
`registry_add`	注册一个新的CM；立即将其添加到连接池中
`registry_deactivate`	软删除CM(`active=FALSE`)；行保留用于审核历史记录
`registry_update_field`	更新给定CM主机的单个字段（端口、api_version、超时…）
`registry_reload`	强制从Iceberg重新加载注册表缓存并刷新连接池

CM注册表（冰山表）

CM实例存储在冰山表中 cdp_registry.cloudera_managers. 完整的DDL、示例数据和常见的更新操作都在 docs/registry_table.sql.

要创建表并插入第一条记录，请执行以下操作：

impala-shell -f docs/registry_table.sql

服务器在启动时读取表并将结果缓存在内存中。缓存每 IMPALA_REFRESH_INTERVAL_SECS 秒（默认值为300）。要强制立即重新加载而不重新启动服务器，请调用 registry_reload 工具。

安全注意事项

CM证书 仅存储在冰山注册表中，从不存储在环境变量或配置文件。
密码注册表中当前以明文形式存储。对于生产部署，集成 cryptography.Fernet 或云机密管理器（AWS机密管理器、Azure密钥库、GCP机密管理器）在 cm_registry.load() 呼叫站点。
刀具输出 从不包括CM密码。这 registry_list 工具明确排除 password 从SELECT语句中删除列。
敏感的CM配置参数 (sensitive=true)通过而不被服务器记录。
破坏性工具 (update_config, run_service_command, registry_deactivate)应通过代理级别确认步骤进行门控在实际调用工具之前。这在代理提示符处强制执行级别，而不是服务器级别。
使用一个 专用CM服务帐户 (svc-mcp-agent)最低限度所需权限，而不是 admin 用户。

使用说明

云时代经理mcp

目录

建筑

项目结构

先决条件

安装

配置

可变组

SQL后端选择

最小化 .env 用于开发（Impala，无TLS）

最小化 .env 用于生产（HiveServer2、LDAP、TLS）

在本地运行

Cloudera Agent Studio中的部署

模式A——本地结账（开发）

模式B——Git存储库（暂存/CI）

模式C——本地车轮（气隙/生产）

外露工具

CM操作工具

注册表管理工具

CM注册表（冰山表）

安全注意事项

相关 MCP

Loki日志查询服务

MCP服务器安装工具

NodeMCU设备管理服务

客户端配置管理服务器

Loki日志查询服务

Excel SQL查询服务器

最小化 `.env` 用于开发（Impala，无TLS）

最小化 `.env` 用于生产（HiveServer2、LDAP、TLS）