Apache Zeppelin Server

An MCP (Model Context Protocol) server that wraps the Apache Zeppelin REST API, allowing LLM agents in Claude Desktop and Claude Code to interact with Zeppelin notebooks.

Prerequisites

• uv installed
• A running Apache Zeppelin instance with REST API enabled
• Zeppelin credentials (username and password)

Available Tools

Tool	Description
list_notebooks	List notebooks, with optional name_filter and limit (default 100)
search_notebooks	Full-text search across all notebook paragraphs, with max_results (default 20)
get_notebook	Get notebook overview with all paragraph code, titles, and status (no output)
list_paragraphs	List paragraph metadata (index, id, title, status) without code or output
get_paragraph	Get full content of a single paragraph (code, output, and dynamic forms)
get_paragraph_code	Get only the code/text content of a paragraph, without output or forms (saves tokens)
get_paragraph_forms	Get dynamic form definitions and current parameter values for a paragraph
update_paragraph_forms	Update dynamic form values without re-executing (preserves chart settings)
update_paragraph_config	Update paragraph visualization/chart config (graph type, column mappings, display settings)
batch_update_paragraph_config	Batch: update visualization/chart config for several paragraphs in one call
update_paragraph	Update paragraph code/text with automatic backup of previous version
batch_update_paragraph	Batch: update several paragraphs in one call (each changed paragraph is backed up)
delete_paragraph	Delete a paragraph with automatic backup of its content
batch_delete_paragraph	Batch: delete several paragraphs in one call (each is backed up first)
move_paragraph	Move a paragraph to a new position within the same notebook
create_notebook	Create a new empty notebook
add_paragraph	Add a new paragraph to an existing notebook
batch_add_paragraph	Batch: add several paragraphs in one call, created in the given order
clone_paragraph	Clone a paragraph (code, title, and chart config) directly below the original
run_paragraph	Run a paragraph and return the result (preserves chart settings)
batch_run_paragraph	Batch: run several paragraphs sequentially in a given order (stops on first error by default)
run_paragraph_async	Start paragraph execution without waiting — for parallel runs, check status with get_paragraph_status
run_all_paragraphs	Run all paragraphs in a notebook and wait for completion (preserves chart settings)
get_paragraph_status	Check execution status of a paragraph
stop_paragraph	Stop a running paragraph (cancel long-running or stuck queries)
get_notebook_permissions	Get permission information for a notebook (owners, writers, readers)
set_notebook_permissions	Set owners, writers, and readers for a notebook
export_notebook	Export notebook as JSON for backup or cross-server migration
import_notebook	Import a previously exported notebook JSON
clone_notebook	Clone an existing notebook with optional rename

Edit and delete operations automatically back up previous paragraph content to protected ~Backups notebooks before making changes.

Skills

The repo also ships two Claude Code skills that encode notebook-workflow best practices (installed automatically with the plugin setup below):

• /notebook — create notebooks, add/edit paragraphs, configure charts and dynamic forms; finalizes every paragraph with the code editor hidden and auto-re-run disabled.
• /review_notebook — structured notebook review: methodology, conclusions, code quality, visualization, documentation.

Ways to use this project

1. Claude Code plugin (recommended) — one command installs the MCP server and the skills, and auto-updates on every commit. See below.
2. Plain MCP server — register the server manually in Claude Desktop / Claude Code / any MCP client; skills are not included. See the setup sections further down.
3. Building block for a private setup — teams can keep their own wrapper plugin (pinned URL, internal skills) in a private marketplace and launch this server from git without cloning: uvx --from git+https://github.com/german-borisevich/apache-zeppelin-mcp@<tag> apache-zeppelin-mcp

Setup as a Claude Code plugin (recommended)

1. Export credentials in your shell profile (the server inherits them from the environment):

export ZEPPELIN_BASE_URL="http://your-zeppelin-host:8080"
export ZEPPELIN_USERNAME="your-username"
export ZEPPELIN_PASSWORD="your-password"

2. In Claude Code:

/plugin marketplace add german-borisevich/apache-zeppelin-mcp
/plugin install apache-zeppelin@apache-zeppelin-mcp

3. Restart the session. The Zeppelin MCP tools and the /notebook, /review_notebook skills are now available, and the plugin auto-updates at session start whenever this repo gets new commits.

Setup for Claude Desktop

1. Open Claude Desktop settings and navigate to the MCP servers configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Zeppelin server to the mcpServers section:

{
  "mcpServers": {
    "zeppelin": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/apache-zeppelin-mcp",
        "run", "server.py"
      ],
      "env": {
        "ZEPPELIN_BASE_URL": "http://your-zeppelin-host:8080",
        "ZEPPELIN_USERNAME": "your-username",
        "ZEPPELIN_PASSWORD": "your-password"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/apache-zeppelin-mcp with the actual absolute path to this project directory.

3. Restart Claude Desktop. The Zeppelin tools will appear in the tools menu (hammer icon).

Setup for Claude Code

Global (all sessions)

Run the following command to register the server for every Claude Code session:

claude mcp add zeppelin \
  -e ZEPPELIN_BASE_URL=http://your-zeppelin-host:8080 \
  -e ZEPPELIN_USERNAME=your-username \
  -e ZEPPELIN_PASSWORD=your-password \
  -- uv --directory /ABSOLUTE/PATH/TO/apache-zeppelin-mcp run server.py

Replace the URL, credentials, and path with your actual values.

To verify it was added:

claude mcp list

To remove it later:

claude mcp remove zeppelin

Project-scoped (single project only)

To make the server available only when Claude Code is running inside a specific project, add a .mcp.json file to the project root:

{
  "mcpServers": {
    "zeppelin": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/apache-zeppelin-mcp",
        "run", "server.py"
      ],
      "env": {
        "ZEPPELIN_BASE_URL": "http://your-zeppelin-host:8080",
        "ZEPPELIN_USERNAME": "your-username",
        "ZEPPELIN_PASSWORD": "your-password"
      }
    }
  }
}

Replace the URL, credentials, and path with your actual values.

The server will only be loaded when Claude Code is started from that project directory (or a subdirectory). Other projects and global sessions will not see the Zeppelin tools.

Tip: If .mcp.json contains credentials you don't want to commit, add it to your .gitignore.

Verifying the Connection

1. Check that the server starts

Run the server directly to confirm it starts without errors:

ZEPPELIN_BASE_URL=http://your-zeppelin-host:8080 \
ZEPPELIN_USERNAME=your-username \
ZEPPELIN_PASSWORD=your-password \
uv run server.py

If configuration is correct the server will authenticate with Zeppelin and then wait for input on stdin (this is normal — it communicates via the MCP stdio protocol). Press Ctrl+C to stop.

If environment variables are missing you will see a ValueError immediately. If credentials are wrong, you will see an authentication error at startup.

2. Test tools with MCP Inspector

The MCP Inspector provides a web UI for testing each tool interactively:

ZEPPELIN_BASE_URL=http://your-zeppelin-host:8080 \
ZEPPELIN_USERNAME=your-username \
ZEPPELIN_PASSWORD=your-password \
mcp dev server.py

This opens a browser where you can:

• See all 30 registered tools
• Call list_notebooks to verify the connection to Zeppelin is working
• Test search_notebooks with a keyword
• Try get_notebook with a notebook ID from the list
• Create a test notebook, add a paragraph, run it, and check the result

3. Test from Claude Desktop

After adding the server to claude_desktop_config.json and restarting Claude Desktop:

1. Open a new conversation
2. Click the hammer icon at the bottom of the input box — you should see all 30 Zeppelin tools listed
3. Ask Claude: "List all my Zeppelin notebooks"
4. Claude will call list_notebooks and show the results

If the tools don't appear, check the Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\Logs\mcp*.log

4. Test from Claude Code

After adding the server with claude mcp add:

1. Start Claude Code: claude
2. Ask: "List all my Zeppelin notebooks"
3. Claude will call list_notebooks — approve the tool call when prompted

5. End-to-end smoke test

Ask the agent to run through this sequence to fully verify all tools:

1. List all notebooks
2. Search for "select" (or any keyword likely in your notebooks)
3. Get the details of one notebook from the list
4. Create a new notebook called "MCP Test"
5. Add a paragraph with: %md Hello from MCP!
6. Run that paragraph
7. Check the paragraph status

If all steps succeed, the server is fully operational.

Automatic Backup

When update_paragraph/batch_update_paragraph or delete_paragraph/batch_delete_paragraph modifies existing content, the previous version is automatically saved to a backup notebook before the change is applied.

• Backup location: Users/<username>/~Backups/<original_notebook_path>/<notebook_name>_<notebook_id>_backup (mirrors the original path)
• What triggers a backup: update_paragraph/batch_update_paragraph (per paragraph, only when text actually changes), delete_paragraph/batch_delete_paragraph (always, per paragraph)
• What doesn't trigger a backup: move_paragraph, title-only changes, add_paragraph
• Protection: All mutating tools (add, run, update, delete, move, set permissions) are blocked from operating on ~Backups notebooks. Read-only tools work normally on backup notebooks.
• Backup paragraph titles include a UTC timestamp and operation label, e.g. [2025-01-15 14:30 UTC | EDIT] paragraph_20250115-143012_123456

If backup creation fails, the destructive operation is aborted — no data is lost.

Troubleshooting

Problem	Cause	Fix
ValueError: ZEPPELIN_BASE_URL environment variable is required	Missing env vars	Set all three env vars (ZEPPELIN_BASE_URL, ZEPPELIN_USERNAME, ZEPPELIN_PASSWORD)
httpx.ConnectError	Zeppelin is unreachable	Verify ZEPPELIN_BASE_URL is correct and Zeppelin is running
Authentication error at startup	Wrong credentials	Check ZEPPELIN_USERNAME and ZEPPELIN_PASSWORD
Tools don't appear in Claude Desktop	Config error or server crash	Check the MCP log files and verify claude_desktop_config.json syntax
Tools don't appear in Claude Code	Server not registered	Run claude mcp list and re-add if missing

Note: The server automatically re-authenticates when sessions expire (including HTTP 302 redirects to the login page). You should not need to manually restart the server due to session timeouts.