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)
update_paragraph	Update paragraph code/text with automatic backup of previous version
delete_paragraph	Delete a paragraph with automatic backup of its content
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
run_paragraph	Run a paragraph synchronously and return the result (preserves chart settings)
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

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

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 22 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 22 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 or 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 (only when text actually changes), delete_paragraph (always)
• 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.