Apache Zeppelin MCP Server

Apache Zeppelin MCP 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, each optionally with its own dynamic-form params (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"

1. In Claude Code:

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

1. 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

1. 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.

1. 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.