Skip to main content
Glama
deenesjakoruzh
ukonduru91

Spark History Server MCP

by ukonduru91
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Spark History Server MCP (TypeScript)

让 LLM 读取你的 Spark History Server，以便它完成 Spark 工作中繁琐的部分：找出作业失败的原因，以及找出慢作业的时间花在哪里。

这是 kubeflow/mcp-apache-spark-history-server 的 TypeScript 移植版，已针对 Python 原版逐响应验证——参见 PARITY.md。在移植的基础上，它还提供了两个代理技能，将原始工具转化为用于根因分析和性能调优的专家工作流。

                    ┌──────────────────┐
  data engineer ──▶ │  LLM client      │   Claude Code / Claude Desktop / any MCP client
                    │  + skills        │   ← skills/ supply the method
                    └────────┬─────────┘
                             │ MCP (stdio or streamable-http)
                    ┌────────▼─────────┐
                    │  this server     │   17 tools, 2 prompts
                    └────────┬─────────┘
                             │ HTTP  GET /api/v1/...
                    ┌────────▼─────────┐
                    │ Spark History    │   your existing one, or the bundled demo
                    │ Server           │
                    └────────┬─────────┘
                             │ reads
                    ┌────────▼─────────┐
                    │ event logs       │   s3://…, hdfs://…, file://…
                    └──────────────────┘

该服务器只向 History Server 的 REST API 发出 GET 请求。它无法修改任何内容。

目录

  1. 快速开始

  2. 指向你的 Spark History Server

  3. 连接你的 LLM 客户端

  4. 安装技能

  5. 工具

  6. 工作原理

  7. 部署

  8. 故障排除

  9. 开发

Related MCP server: Spark EventLog MCP Server

1. 快速开始

选项 A — Docker（除了 Docker 无需安装任何东西）

启动一个加载了示例事件日志的 Spark History Server 以及 这个 MCP：

git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
docker compose up --build

Spark History Server UI

http://localhost:18080

Spark History REST API

http://localhost:18080/api/v1/applications

MCP 端点

http://localhost:18888/mcp

捆绑的日志包括一个健康的管道和一个故意失败的作业，因此在指向你自己的集群之前，工具会有一些真实的东西可以展示。

仅运行 History Server：

./start_local_spark_history.sh          # macOS / Linux / Git Bash
.\start_local_spark_history.ps1         # Windows PowerShell

选项 B — 从源码运行

需要 Node.js 20+（推荐 22）。

git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
npm install
npm run build
npm start

验证它是否工作

node scripts/mcp-cli.mjs list-tools
node scripts/mcp-cli.mjs call list_applications '{"limit": 5}'

如果返回了应用程序，说明你已连接。

2. 指向你的 Spark History Server

这是你必须配置的一项。 有三种方式，优先级从高到低——环境变量优先于 .env 文件，后者优先于 YAML。

a. 环境变量（最适合容器和 CI）

嵌套使用双下划线。下面的 LOCAL 只是你为服务器选择的一个名称：

export SHS_SERVERS__LOCAL__URL=http://spark-history.internal:18080
export SHS_SERVERS__LOCAL__DEFAULT=true

b. YAML 配置文件

服务器按以下顺序查找：

  1. 通过 --config 或 $SHS_MCP_CONFIG 指定的路径

  2. 工作目录中的 ./config.yaml

  3. ~/.config/spark-mcp/config.yaml

servers:
  prod:
    url: "https://spark-history.company.com:18080"
    default: true          # used when a tool call omits `server`
    verify_ssl: true
    ssl_ca_cert: "/etc/ssl/custom-ca/ca-bundle.pem"   # private CA
    timeout: 30            # seconds
    auth:
      username: admin
      password: ${SPARK_PASSWORD}   # see the note below
      # token: <bearer token>       # or a bearer token instead

  staging:
    url: "https://spark-history-staging.company.com:18080"

关于密钥：YAML 中的值是字面量——${SPARK_PASSWORD} 不会 被展开。请将凭据保存在环境变量中 （SHS_SERVERS__PROD__AUTH__PASSWORD），它们会覆盖文件。这与上游项目的行为一致。

c. .env 文件

变量名与 (a) 相同，从工作目录中的 .env 读取。

多个服务器

可以配置任意多个。工具接受可选的 server 参数；当省略时，服务器会发现哪个已配置的 History Server 拥有该应用程序并使用它（缓存 5 分钟）。因此，工程师可以询问一个应用程序 ID，而无需知道它运行在哪个集群上。

所有设置

设置

环境变量

默认值

含义

servers.<n>.url

SHS_SERVERS__<N>__URL

http://localhost:18080

History Server 基础 URL

servers.<n>.default

SHS_SERVERS__<N>__DEFAULT

false

未指定 server 时使用

servers.<n>.auth.username

SHS_SERVERS__<N>__AUTH__USERNAME

—

基本认证

servers.<n>.auth.password

SHS_SERVERS__<N>__AUTH__PASSWORD

—

基本认证

servers.<n>.auth.token

SHS_SERVERS__<N>__AUTH__TOKEN

—

Bearer 令牌

servers.<n>.verify_ssl

SHS_SERVERS__<N>__VERIFY_SSL

true

TLS 验证

servers.<n>.ssl_ca_cert

SHS_SERVERS__<N>__SSL_CA_CERT

—

私有 CA 的 PEM 捆绑包

servers.<n>.timeout

SHS_SERVERS__<N>__TIMEOUT

30

请求超时，秒

servers.<n>.use_proxy

SHS_SERVERS__<N>__USE_PROXY

false

通过 socks5h://localhost:8157 路由

servers.<n>.include_plan_description

SHS_SERVERS__<N>__INCLUDE_PLAN_DESCRIPTION

false

get_sql_execution 计划文本的默认值

mcp.transport

SHS_MCP__TRANSPORT

streamable-http

stdio 或 streamable-http

mcp.address

SHS_MCP__ADDRESS

localhost

HTTP 绑定地址

mcp.port

SHS_MCP__PORT

18888

HTTP 绑定端口

mcp.debug

SHS_MCP__DEBUG

false

详细日志

单下划线变量（SHS_MCP_PORT）仍然有效，但会记录弃用警告，与上游完全一致。

访问无法直接路由到的 History Server

SSH 隧道加上 use_proxy: true 可以覆盖常见的锁定集群场景：

ssh -D 8157 -N user@bastion    # SOCKS5 proxy on :8157

3. 连接你的 LLM 客户端

stdio（Claude Code、Claude Desktop、大多数客户端）

{
  "mcpServers": {
    "spark-history": {
      "command": "node",
      "args": ["/absolute/path/to/spark-history-mcp/dist/index.js"],
      "env": {
        "SHS_MCP__TRANSPORT": "stdio",
        "SHS_SERVERS__PROD__URL": "https://spark-history.company.com:18080",
        "SHS_SERVERS__PROD__DEFAULT": "true"
      }
    }
  }
}

Claude Code 用户可以用一行完成同样的事情：

claude mcp add spark-history \
  --env SHS_MCP__TRANSPORT=stdio \
  --env SHS_SERVERS__PROD__URL=https://spark-history.company.com:18080 \
  --env SHS_SERVERS__PROD__DEFAULT=true \
  -- node /absolute/path/to/spark-history-mcp/dist/index.js

streamable-http（团队共享一个服务器）

运行一次，让所有人都指向它：

SHS_MCP__TRANSPORT=streamable-http SHS_MCP__ADDRESS=0.0.0.0 npm start

客户端连接到 http://<host>:18888/mcp。服务器是只读的，但也是未认证的——请将其放在你正常的内部入口后面，如果它可以从浏览器访问，请启用 DNS 重绑定保护：

mcp:
  transport_security:
    enable_dns_rebinding_protection: true
    allowed_hosts: ["spark-mcp.internal:*"]
    allowed_origins: ["https://spark-mcp.internal"]

4. 安装技能

工具让模型能够访问数据。技能则赋予它方法——收集证据的顺序、区分发现与噪音的阈值，以及不得说出数据中未出现的因果的规则。

# per project
mkdir -p .claude/skills
cp -r skills/spark-rca skills/spark-optimization .claude/skills/

# or for every project
mkdir -p ~/.claude/skills
cp -r skills/spark-rca skills/spark-optimization ~/.claude/skills/

技能

处理对象

触发条件

spark-rca

失败、被杀死或挂起的作业

"为什么失败了"、堆栈跟踪、应用 ID、"OOM"、"卡住"

spark-optimization

慢、昂贵或性能回退的作业

"为什么这么慢"、"调优"、"以前需要 20 分钟"、"降低成本"

它们会从正常问题中自行触发——没有人需要记住命令：

"凌晨 2 点的加载又失败了，app_1724…——你能看一下吗？"

参见 skills/README.md 了解每个技能的内容以及如何用你自己团队的知识扩展它们。

5. 工具

全部 17 个工具位于 src/tools/tools.ts；它们的 JSON 模式在 src/schemas/generated.ts 中。运行 node scripts/mcp-cli.mjs list-tools 可以查看它们及其参数。

查找内容

工具

返回内容

list_applications

应用程序，可按状态和日期过滤，或按 app_id 获取单个应用程序

list_jobs

应用程序的作业——默认先显示失败的；sort_by 支持 duration / failed-tasks / id

list_stages

阶段，相同的排序选项，可选的汇总指标

list_executors

执行器，默认显示活跃的，include_inactive 显示完整历史

list_sql_executions

精选的 SQL 执行摘要，可按描述过滤

深入分析

工具

返回内容

get_stage

单个阶段，按你的分位数显示每个任务的指标分布

list_stage_task_failures

每个任务的异常和堆栈跟踪——根因所在

get_sql_execution

单个查询：头部、物理计划、每个节点的指标、作业、阶段

get_environment

运行时版本、Spark/系统/Hadoop 属性、类路径——按 section 过滤

get_executor_summary

应用程序的聚合执行器指标

get_executor_thread_dump

JVM 线程转储——仅限正在运行的应用程序

诊断

工具

返回内容

get_job_bottlenecks

最慢的阶段和作业、溢出、GC 压力、利用率、建议

get_resource_usage_timeline

执行器添加/移除和阶段时间线摘要

比较两次运行

工具

返回内容

compare_job_environments

配置差异——两次运行之间发生了什么变化

compare_job_performance

资源和持续时间差异

compare_sql_executions

两个查询的指标差异，以及可选的计划结构差异

compare_stages

阶段指标和任务分位数并排显示

提示

investigate_failure(app_id, server?) 和 compare_applications(app_a, app_b, server?, context?)——来自上游项目的交互式演练，适用于工程师想要自己驱动而不是将分析交给模型的情况。

6. 工作原理

一次工具调用会变成对 /api/v1/... 的一次或多次 GET 请求，返回的 JSON 形状与 Python 原版完全一致。

src/
  index.ts                 CLI entry, transport selection (stdio | streamable-http)
  config/config.ts         YAML + .env + SHS_* resolution and precedence
  core/
    app.ts                 MCP request handlers; maps results to content blocks
    validation.ts          pydantic-compatible argument validation and messages
    json.ts                Python-compatible JSON rendering
    pyfloat.ts             int/float fidelity across the JSON round-trip
    pyrepr.ts              Python repr() for validation messages
    errors.ts              error text shaping
  api/
    httpClient.ts          HTTP transport, ApiException taxonomy, auth, TLS, SOCKS
    sparkClient.ts         Spark REST facade: pagination, attempts, status filters
  models/
    generated.ts           model shapes, generated from the upstream OpenAPI models
    deserialize.ts         from_dict / model_dump equivalents
    mcpTypes.ts            curated LLM-facing output models
  tools/tools.ts           the 17 tools
  prompts/prompts.ts       the 2 prompts
  schemas/generated.ts     tool + prompt catalogue (names, descriptions, schemas)

如果你打算修改它，有三个值得了解的细节：

  • models/generated.ts 和 schemas/generated.ts 是生成的，由 tools/gen_models.py 和 tools/gen_schemas.py 从上游 Python 项目生成。请重新生成而不是手动编辑——这样才能保持目录和 响应形状与原版一致。

  • 使用底层 Server API，而不是 McpServer，因为结果 形状必须与 FastMCP 匹配：每个列表元素一个文本块， 并且只有 Python 签名声明了具体返回类型的工具才使用 structuredContent。

  • 应用程序发现允许工具省略 server。ApplicationDiscovery 探测每个配置的服务器以查找应用程序 ID，并将答案缓存 5 分钟。

7. 部署

Docker

docker build -t spark-history-mcp .
docker run -p 18888:18888 \
  -e SHS_SERVERS__PROD__URL=https://spark-history.company.com:18080 \
  -e SHS_SERVERS__PROD__DEFAULT=true \
  -e SHS_MCP__ADDRESS=0.0.0.0 \
  spark-history-mcp

Kubernetes

将其作为普通 Deployment 运行，URL 放在环境变量中，凭据来自 Secret：

env:
  - name: SHS_MCP__TRANSPORT
    value: streamable-http
  - name: SHS_MCP__ADDRESS
    value: "0.0.0.0"
  - name: SHS_SERVERS__PROD__URL
    value: http://spark-history-server.spark.svc.cluster.local:18080
  - name: SHS_SERVERS__PROD__DEFAULT
    value: "true"
  - name: SHS_SERVERS__PROD__AUTH__TOKEN
    valueFrom:
      secretKeyRef: { name: spark-history-auth, key: token }

该进程除了 5 分钟的发现缓存外是无状态的，因此无需协调即可水平扩展。

8. 故障排查

症状

原因与修复

connect ECONNREFUSED

URL 或端口错误，或历史服务器已关闭。从同一主机运行 curl $URL/api/v1/applications 检查

Application '<id>' not found on any server

该 id 不在任何已配置的服务器上，或者事件日志尚未被拾取 — spark.history.fs.update.interval 控制扫描

No Spark server named 'x' is configured

server 参数与 servers: 下的键不匹配

404 … No tasks reported metrics for N / 0 yet

这是 Spark 对某个在任何任务完成前就失败的阶段的回答。不是工具问题 — 请阅读任务异常

get_executor_thread_dump 在已完成的应用程序上出错

预期行为：历史服务器不持久化线程转储。它们仅在应用程序运行时有效

空的 list_applications

检查 spark.history.fs.logDirectory 指向你的作业实际写入事件日志的位置，并且作业上 spark.eventLog.enabled=true

非常大的响应

使用 length、limit 和 section 缩小范围。get_stage(with_summaries=false) 要小得多

emr_cluster_arn … not included in this TypeScript port

EMR 持久化 UI 认证未移植；请指向可直接访问的 URL 代替

设置 SHS_MCP__DEBUG=true 以获取详细日志。

9. 开发

npm install
npm run build        # compile to dist/
npm run dev          # run from source, no build step
npm test             # unit tests
npm run typecheck    # tsc --noEmit

跨实现一致性测试位于 parity/ — 它针对此服务器和 Python 原版运行相同的 MCP 调用，并对每个响应进行差异比较。PARITY.md 记录了结果和仍然存在的确切差异。

未从上游移植

上游模块

状态

api/emr_persistent_ui_client.py

未移植 — 配置了 emr_cluster_arn 的服务器会快速失败并给出解释性错误

tools/aws_troubleshooting.py

未移植 — 代理到 AWS 托管的 MCP 端点，仅在存在 AWS 凭据时注册

api/spark_html_client.py

未移植 — 一个 Playwright 截图辅助工具，没有工具调用

许可证

Apache-2.0，与上游项目相同。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • CDM MCP Server

    KBaseDataLakehouse
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to interact with Delta Lake tables stored in MinIO through Spark using natural language queries. Provides read-oriented data operations on Delta Lake tables through the Model Context Protocol.

  • Spark EventLog MCP Server

    yhyyz
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables comprehensive analysis of Apache Spark event logs from S3, HTTP, or local sources, providing performance metrics, resource monitoring, shuffle analysis, and automated optimization recommendations with interactive HTML reports.
    MIT

  • Spark History MCP Server

    ravipesala
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Exposes Spark History Server metrics and metadata as tools for LLM-based analysis of Spark applications. It enables deep optimization of Spark jobs by providing access to job summaries, stage details, SQL execution plans, and executor performance.

  • Apache Spark History Server

    kubeflow
    A
    license
    Not graded
    quality
    A
    maintenance
    Exposes Spark History Server data as tools for AI agents, enabling natural language querying of Spark applications, jobs, stages, and performance metrics.
    189
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • mcp

    The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.

  • ScrapeGraphAI-scrapegraph-mcp

    Enable language models to perform advanced AI-powered web scraping with enterprise-grade reliabili…

  • APICK AI

    LLM chat, text summarization and AI image generation

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ukonduru91/spark-history-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server