Skip to content

[ZEPPELIN-6434] Add MCP server for operating notebooks from AI agents#5277

Open
kkalyan wants to merge 2 commits into
apache:masterfrom
kkalyan:ZEPPELIN-6434-mcp-server
Open

[ZEPPELIN-6434] Add MCP server for operating notebooks from AI agents#5277
kkalyan wants to merge 2 commits into
apache:masterfrom
kkalyan:ZEPPELIN-6434-mcp-server

Conversation

@kkalyan

@kkalyan kkalyan commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

What is this PR for?

Adds zeppelin-mcp, a Model Context Protocol (MCP) server that lets AI coding
agents — Claude Code, Kiro, Codex, Cursor, and any other MCP client — operate an
Apache Zeppelin instance: select or create a notebook, run paragraphs in any
interpreter, read results, delete paragraphs, clear output, restart a stuck
interpreter, and write a summary back into the notebook.

The server is a thin client over the existing Zeppelin REST API, so it works
against any reachable Zeppelin server without server-side changes. It is
implemented in Python on the official MCP SDK (FastMCP), mirroring the existing
python/ module's precedent for Python-in-the-reactor.

This PR also adds zeppelin-mcp/GETTING_STARTED.md, a build-from-source guide
for the current experimental phase: prerequisites, venv install, a stdio smoke
test, the env-var configuration table, MCP client wiring for Claude Code / Kiro
/ Codex / generic clients, the tool reference, and troubleshooting.

What type of PR is it?

Feature

What is the Jira issue?

https://issues.apache.org/jira/browse/ZEPPELIN-6434

How should this be tested?

mvn test -pl zeppelin-mcp creates a venv under target/venv and runs the
pytest suite (61 tests, 97% line coverage) against an in-memory fake Zeppelin —
no live server required. RAT passes (0 unapproved licenses).

For a manual end-to-end check, point an MCP client at a local Zeppelin:

claude mcp add zeppelin --env ZEPPELIN_URL=http://localhost:8080 -- zeppelin-mcp

Open items (tracked for follow-up, not blocking)

  • Binary distribution. Whether to bundle the zeppelin-mcp console script
    inside the Zeppelin binary distribution vs. publishing to PyPI for
    pip install. Currently build-from-source only.
  • Standard distribution channel — PyPI release cadence and versioning.
  • Semantic search as agent knowledge. Optionally index notebook/paragraph
    text plus interpreter metadata so an agent can discover relevant notebooks by
    meaning (e.g. a search_notebooks tool) and build richer context, rather than
    only operating on an explicitly selected note. Not implemented today.

Questions:

  • Does the license files need to update? No
  • Is there breaking changes for older versions? No
  • Does this needs documentation? Module README + GETTING_STARTED.md added; a
    docs page under docs/ can follow.
image

Kalyan Kanuri added 2 commits June 26, 2026 09:10
### What is this PR for?

Adds `zeppelin-mcp`, a Model Context Protocol (MCP) server that lets AI
coding agents — Claude Code, Kiro, Cursor, and any other MCP client —
operate an Apache Zeppelin instance: select or create a notebook, run
paragraphs in any interpreter, read results, delete paragraphs, clear
output, restart a stuck interpreter, and write a summary back into the
notebook.

The server is a thin client over the existing Zeppelin REST API, so it
works against any reachable Zeppelin server without server-side changes.
It is implemented in Python on the official MCP SDK (FastMCP), mirroring
the existing `python/` module's precedent for Python-in-the-reactor.

### What type of PR is it?

Feature

### What is the Jira issue?

https://issues.apache.org/jira/browse/ZEPPELIN-6434

### How should this be tested?

`mvn test -pl zeppelin-mcp` creates a venv under `target/venv` and runs
the pytest suite (61 tests, 97% line coverage) against an in-memory fake
Zeppelin — no live server required. RAT passes (0 unapproved licenses).

For a manual end-to-end check, point an MCP client at a local Zeppelin:

    claude mcp add zeppelin --env ZEPPELIN_URL=http://localhost:8080 -- zeppelin-mcp

### Questions:

* Does the license files need to update? No
* Is there breaking changes for older versions? No
* Does this needs documentation? Yes — module README added; a docs page
  under `docs/` can follow.
Build-from-source guide for the experimental MCP server: prerequisites,
venv install, smoke test, env-var config, MCP client wiring for Claude
Code / Kiro / Codex / generic clients, the tool reference, and
troubleshooting. Records open items (binary distribution, PyPI channel,
semantic-search-as-knowledge) pending follow-up.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant