# 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](https://docs.astral.sh/uv/getting-started/installation/) 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):

```bash
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:

```json
{
  "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:

```bash
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:

```bash
claude mcp list
```

To remove it later:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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.