Apache Zeppelin MCP

Apache Zeppelin MCP服务器

一个MCP（模型上下文协议）服务器，它封装了Apache Zeppelin REST API，允许Claude Desktop和Claude Code中的LLM代理与Zeppelin笔记本电脑交互。

先决条件

• 紫外线 安装
• 启用REST API的运行中的Apache Zeppelin实例
• 齐柏林飞船凭据（用户名和密码）

可用工具

编辑和删除操作会自动将上一段内容备份到受保护的位置 ~Backups 在进行更改之前，请在笔记本电脑上。

Claude桌面设置

1. 打开Claude Desktop设置并导航到MCP服务器配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

1. 将Zeppelin服务器添加到 mcpServers 章节：

{
  "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"
      }
    }
  }
}

替换 /ABSOLUTE/PATH/TO/apache-zeppelin-mcp 带有此项目目录的实际绝对路径。

1. 重新启动克劳德桌面。齐柏林飞船工具将出现在工具菜单中（锤子图标）。

Claude代码的设置

全球（所有会议）

运行以下命令为每个Claude Code会话注册服务器：

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

将URL、凭据和路径替换为实际值。

要验证是否已添加：

claude mcp list

要稍后删除它，请执行以下操作：

claude mcp remove zeppelin

项目范围（仅限单个项目）

要使服务器仅在Claude Code在特定项目中运行时可用，请添加 .mcp.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"
      }
    }
  }
}

将URL、凭据和路径替换为实际值。

只有从该项目目录（或子目录）启动Claude Code时，才会加载服务器。其他项目和全球会议将不会看到齐柏林飞船工具。

提示： 如果 .mcp.json 包含您不想提交的凭据，请将其添加到您的 .gitignore.

验证连接

1.检查服务器是否启动

直接运行服务器以确认其无错误启动：

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

如果配置正确，服务器将使用Zeppelin进行身份验证，然后等待stdin上的输入（这是正常的——它通过MCP stdio协议进行通信）。按 Ctrl+C 停止。

如果缺少环境变量，您将看到 ValueError 立即。如果凭据错误，您将在启动时看到身份验证错误。

2.带MCP检验员的测试工具

MCP检查器提供了一个web UI，用于交互式测试每个工具：

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

这将打开一个浏览器，您可以在其中：

• 查看所有22个已注册的工具
• 呼叫 list_notebooks 验证与齐柏林飞船的连接是否正常
• 测试 search_notebooks 带有关键字
• 尝试 get_notebook 使用列表中的笔记本ID
• 创建一个测试笔记本，添加一个段落，运行它，并检查结果

3.克劳德桌面测试

将服务器添加到后 claude_desktop_config.json 并重新启动Claude Desktop：

1. 打开新对话
2. 点击输入框底部的锤子图标——您应该看到列出的所有22个齐柏林飞船工具
3. 问克劳德： *“列出我所有的齐柏林飞船笔记本”*
4. 克劳德会打电话的 list_notebooks 并显示结果

如果工具未出现，请检查Claude Desktop日志：

• macOS： ~/Library/Logs/Claude/mcp*.log
• 窗户： %APPDATA%\Claude\Logs\mcp*.log

4.克劳德代码测试

添加服务器后 claude mcp add:

1. 启动克劳德代码： claude
2. 问： *“列出我所有的齐柏林飞船笔记本”*
3. 克劳德会打电话的 list_notebooks --在系统提示时批准工具调用

5.端到端烟雾测试

要求代理运行此序列以完全验证所有工具：

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

如果所有步骤都成功，则服务器完全可以运行。

自动备份

当 update_paragraph 或 delete_paragraph 修改现有内容时，在应用更改之前，以前的版本会自动保存到备份笔记本中。

• 备份位置： Users//~Backups//__backup （镜像原始路径）
• 触发备份的原因： update_paragraph （仅当文本实际发生变化时）， delete_paragraph （总是）
• 什么不会触发备份： move_paragraph，仅标题更改， add_paragraph
• 保护： 所有变异工具（添加、运行、更新、删除、移动、设置权限）都被阻止在 ~Backups 笔记本电脑。只读工具在备份笔记本上正常工作。
• 备份段落标题 包括UTC时间戳和操作标签，例如。 [2025-01-15 14:30 UTC | EDIT] paragraph_20250115-143012_123456

如果备份创建失败，则破坏性操作将中止，不会丢失任何数据。

故障排除

注： 当会话过期时，服务器会自动重新进行身份验证（包括HTTP 302重定向到登录页面）。由于会话超时，您不需要手动重新启动服务器。