AI导哈

Databricks工具服务器

一个为AI代理提供与Databricks工作区交互的全面工具集的FastMCP服务器，支持目录管理、查询执行、集群管理、作业管理、笔记本操作和DBFS文件系统操作。

  • by octavioccl
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 octavioccl/databricks-mcp-server

使用说明

_CHMCP服务器

全面 FastMCP 该服务器为AI代理提供了强大的工具，用于与Rancher工作区进行交互。采用现代MCP最佳实践，使用个人 @mcp.tool() 在一个高效的服务器中实现装饰功能。

🚀 建筑

此项目使用 统一的FastMCP服务器架构 所有工具均单独实施 @mcp.tool() 装饰功能，提供：

  • 35+MCP工具 涵盖6个综合类别
  • 单一入口点：简化了部署和管理
  • 异步/等待支持：具有针对Docker环境的事件循环冲突处理功能
  • JSON响应：结构化、一致的工具输出
  • 线程安全：并行工具执行支持
  • Docker就绪：针对Poetry的容器化部署进行了优化

✨ 特性

🗄️ 目录管理工具 （6个工具）

  • list_catalogs -浏览可用数据目录
  • list_schemas -探索目录中的模式
  • list_tables -发现表格和视图
  • get_table_info -获取详细的表元数据和架构
  • search_tables -使用模式匹配查找表
  • generate_sql_query -基于人工智能的自然语言SQL生成

🔍 高级查询执行 （2个工具）

  • execute_query -使用自动LIMIT处理执行SQL查询
  • execute_statement -具有参数、目录、模式和超时控制的高级SQL执行

🖥️ 群集管理 （7工具）

  • list_clusters -查看所有工作区集群
  • get_cluster -获取详细的集群信息
  • create_cluster -创建具有自动缩放功能的新集群
  • start_cluster -启动已停止的群集
  • terminate_cluster -终止正在运行的群集
  • restart_cluster -重新启动群集进行维护
  • resize_cluster -动态调整集群容量

⚙️ 作业管理 （9个工具）

  • list_jobs -浏览所有工作区作业
  • get_job -获取详细的作业配置
  • run_job -使用自定义参数执行作业
  • create_job -创建新的作业定义
  • update_job -修改现有作业
  • delete_job -删除作业定义
  • get_run -获取作业运行详细信息和状态
  • cancel_run -取消正在运行的作业执行
  • list_runs -浏览作业执行历史记录

📓 笔记本操作 （7工具）

  • list_notebooks -浏览工作区笔记本
  • get_notebook -检索笔记本元数据
  • export_notebook -以多种格式导出（SOURCE、HTML、JUPYTER、DBC）
  • import_notebook -导入带有base64内容的笔记本
  • delete_notebook -安全删除笔记本
  • create_directory -创建工作区目录
  • get_notebook_status -检查笔记本电脑的可用性

📁 DBFS文件系统 （8工具）

  • list_files -浏览DBFS目录
  • get_file -下载文件内容（文本/二进制）
  • put_file -上传base64编码的文件
  • upload_large_file -大文件分块上传
  • delete_file -删除文件和目录
  • get_status -获取文件/目录元数据
  • create_directory -创建DBFS目录
  • move_file -移动/重命名文件和目录

🛠️ 安装和设置

先决条件

  • Python 3.8+
  • jms工作区访问
  • 个人访问令牌或服务主体凭据

快速开始

  1. 安装依赖项：

    pip install fastmcp 'mcp[cli]' databricks-sdk

  2. 设置环境变量：

    export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
export DATABRICKS_TOKEN=your-personal-access-token
export DATABRICKS_SQL_WAREHOUSE_ID=your-warehouse-id  # optional

  3. 运行服务器：

    # Using the CLI script
./bin/databricks-mcp-server

# Or directly with Python
python src/databricks_mcp/servers/main.py

Claude桌面配置

添加到您的Claude Desktop配置文件中：

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

{
  "mcpServers": {
    "databricks": {
      "command": "python",
      "args": ["/path/to/databricks-mcp-server/src/databricks_mcp/servers/main.py"],
      "env": {
        "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
        "DATABRICKS_TOKEN": "your-token-here"
      }
    }
  }
}

🐳 Docker部署

使用Docker Compose

  1. 复制环境配置：

    cp config.env.example config.env
# Edit config.env with your Databricks credentials

  2. 构建并运行：

    docker-compose -f deploy/docker/docker-compose.yml up --build

Claude桌面与Docker

{
  "mcpServers": {
    "databricks": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/config.env",
        "databricks-mcp-server"
      ]
    }
  }
}

🔧 配置

环境变量

必修的：

DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=your-personal-access-token

可选：

DATABRICKS_SQL_WAREHOUSE_ID=your-sql-warehouse-id
DATABRICKS_DEFAULT_CATALOG=main
DATABRICKS_DEFAULT_SCHEMA=default
MCP_SERVER_NAME=databricks-mcp
MCP_LOG_LEVEL=INFO
MCP_ENABLE_QUERY_EXECUTION=true
MCP_ENABLE_NATURAL_LANGUAGE=true

安全考虑

  • 安全地存储令牌（环境变量，而不是代码）
  • 使用SQL仓库ID执行查询（推荐）
  • 考虑将只读访问令牌用于生产用途
  • 通过内置查询验证器验证所有SQL查询

🧪 测试与开发

测试连接

./bin/databricks-mcp-server --test

发展模式

# Start with debug logging
./bin/databricks-mcp-server --log DEBUG

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python src/databricks_mcp/servers/main.py

添加新工具

  1. 将您的工具功能添加到 src/databricks_mcp/core/server_fastmcp.py
  2. 使用 @mcp.tool() 装饰器
  3. 遵循既定的错误处理模式
  4. 使用MCP检查员进行测试

例子：

@mcp.tool()
async def my_new_tool(param: str) -> str:
    """Description of what this tool does."""
    try:
        client = get_databricks_client()
        
        # Try async first, fall back to sync in thread if needed
        try:
            result = await client.some_operation(param)
        except RuntimeError as e:
            if "cannot be called from a running event loop" in str(e):
                logger.warning("Event loop conflict detected, running in separate thread")
                result = run_sync_in_thread(client.some_operation(param))
            else:
                raise
        
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({
            "status": "error",
            "error": str(e)
        }, indent=2)

📊 演出

  • 内存使用：每个服务器实例约50-100MB
  • 启动时间：约2-5秒（取决于copula连接）
  • 工具执行：每个工具约100-2000ms（取决于操作）
  • 并发请求：线程安全，支持多个并发工具调用
  • Docker开销：最小的单流程架构

🔍 故障排除

常见问题

  1. AsyncIO事件循环冲突：服务器通过在单独的线程中运行操作来自动处理这些操作
  2. 连接超时：检查您的 DATABRICKS_HOST 和 DATABRICKS_TOKEN
  3. 权限错误：确保您的令牌具有适当的工作区权限
  4. Docker问题：验证环境变量是否正确传递到容器

调试模式

./bin/databricks-mcp-server --log DEBUG --test

日志

服务器提供全面的日志记录。检查日志以了解：

  • 连接状态
  • 工具执行细节
  • 带有建议修复的错误消息
  • 性能指标

📚 文档

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 按照既定模式进行更改
  4. 测试您的更改(python -m py_compile src/databricks_mcp/core/server_fastmcp.py)
  5. 提交您的更改(git commit -m 'Add amazing feature')
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

内置于❤️ 使用FastMCP和Databricks SDK

该服务器提供了AI代理和copula工作区之间的全面接口，通过自然语言交互实现了强大的数据分析、作业管理和工作区自动化。

相关 MCP