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)

Related MCP server: NotebookLM MCP Server

Available Tools

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

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.