Mcp Server

MCP 服务

连接大模型与 Firebolt 数据仓库的模型上下文协议实现

主要功能 | 使用方法 | 连接大模型 | 架构 | 开发

主要功能

与 Firebolt 集成大模型

• 将 AI 助手直接连接到您的数据仓库
• 支持 AI Agent 自主查询数据并生成洞察
• 为大模型提供 Firebolt SQL、功能和文档的深入知识

SQL 查询执行

• 支持多种查询类型和执行模式
• 直接访问 Firebolt 数据库

访问文档

• 授予大模型访问 Firebolt 完整文档、SQL 参考、函数列表等内容的权限

账户管理

• 使用 Firebolt 服务账户实现无缝身份验证
• 连接到不同的引擎和工作区

多平台支持

• 可在支持 Go 二进制文件的平台上运行
• 提供官方 Docker 镜像，便于部署

使用方法

开始之前，请确保您具备以下任一项：

• 拥有一个包含客户端 ID 和客户端密钥的 Firebolt 服务账户。
• 一个 Firebolt Core 实例 URL。

安装 MCP 服务

您可以通过 Docker 运行 Firebolt MCP 服务，也可以下载二进制文件运行。

选项 1：使用 Docker 运行

docker run \
  --rm \
  --network host \
  -e FIREBOLT_MCP_CLIENT_ID=your-client-id \
  -e FIREBOLT_MCP_CLIENT_SECRET=your-client-secret \
  ghcr.io/firebolt-db/mcp-server:0.7.0

选项 2：运行二进制文件

# Download the binary for your OS from:
# https://github.com/firebolt-db/mcp-server/releases/tag/v0.7.0

./firebolt-mcp-server \
  --client-id your-client-id \
  --client-secret your-client-secret

连接大模型

安装 MCP 服务后，您可以连接各种大模型客户端。请在下方选择您的客户端。

Cursor

一键在 Cursor 中安装 Firebolt MCP 服务。您需要在 Cursor Settings > Tools & MCP 中设置凭据（编辑已添加的服务或 mcp.json）。

Firebolt Cloud（服务账户）：

Firebolt Core（本地或可自托管）：

重要

Cursor 尚不支持 MCP 资源。此 MCP 服务大量使用资源，因此除非禁用资源功能，否则无法在 Cursor 中运行。上方按钮已为您设置 FIREBOLT_MCP_DISABLE_RESOURCES=true。如果手动配置，则必须设置此环境变量。

VS Code（Copilot Chat）

要将 MCP 集成到 VS Code 中的 Copilot Chat，请参阅官方指南：使用 Model Context Protocol 扩展 Copilot Chat。

将 Firebolt MCP 服务添加到 MCP 配置中（例如，通过命令面板 > MCP: Open User Configuration）。以下是使用 Docker 连接 Firebolt Cloud 的示例：

{
  "mcpServers": {
    "firebolt": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "FIREBOLT_MCP_CLIENT_ID",
        "-e", "FIREBOLT_MCP_CLIENT_SECRET",
        "ghcr.io/firebolt-db/mcp-server:latest"
      ],
      "env": {
        "FIREBOLT_MCP_CLIENT_ID": "your-client-id",
        "FIREBOLT_MCP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

将 your-client-id 和 your-client-secret 替换为你的 Firebolt 服务账号凭据。

Claude Desktop

使用 Docker 与 Claude Desktop 集成：

1. 打开 Claude 菜单并选择 Settings…。

2. 前往 Developer > Edit Config。

3. 更新配置文件（claude_desktop_config.json），添加以下内容：

   {
     "mcpServers": {
       "firebolt": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "--network", "host",
           "-e", "FIREBOLT_MCP_CLIENT_ID",
           "-e", "FIREBOLT_MCP_CLIENT_SECRET",
           "ghcr.io/firebolt-db/mcp-server:0.7.0"
         ],
         "env": {
           "FIREBOLT_MCP_CLIENT_ID": "your-client-id",
           "FIREBOLT_MCP_CLIENT_SECRET": "your-client-secret"
         }
       }
     }
   }
   

   如需使用二进制文件而非 Docker：

   {
     "mcpServers": {
       "firebolt": {
         "command": "/path/to/firebolt-mcp-server",
         "env": {
           "FIREBOLT_MCP_CLIENT_ID": "your-client-id",
           "FIREBOLT_MCP_CLIENT_SECRET": "your-client-secret"
         }
       }
     }
   }
   

   连接到 Firebolt Core

   如果你使用 Firebolt Core，可以提供 Core URL，而非服务账号凭据来连接。

   使用 Claude Desktop 连接 Firebolt Core：

   {
     "mcpServers": {
       "firebolt": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "--network", "host",
           "-e", "FIREBOLT_MCP_CORE_URL",
           "ghcr.io/firebolt-db/mcp-server:0.7.0"
         ],
         "env": {
           "FIREBOLT_MCP_CORE_URL": "http://localhost:3473"
         }
       }
     }
   }
   

4. 保存配置并重启 Claude Desktop。

更多详情：Claude MCP 快速入门指南

手动配置（其他 MCP 客户端）

对于使用 JSON 配置（例如 mcpServers）的任何 MCP 客户端，都可以通过以下标准配置添加 Firebolt 服务。Firebolt Cloud（Docker）：

{
  "mcpServers": {
    "firebolt": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "host",
        "-e", "FIREBOLT_MCP_CLIENT_ID",
        "-e", "FIREBOLT_MCP_CLIENT_SECRET",
        "ghcr.io/firebolt-db/mcp-server:latest"
      ],
      "env": {
        "FIREBOLT_MCP_CLIENT_ID": "your-client-id",
        "FIREBOLT_MCP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

对于 Firebolt Core，请在 env 中使用 FIREBOLT_MCP_CORE_URL（例如 http://localhost:3473），并在 args 中传入 -e FIREBOLT_MCP_CORE_URL，而不是客户端 ID/密钥。对于 Cursor，还需在 env 和 args 中设置 FIREBOLT_MCP_DISABLE_RESOURCES=true。

使用 SSE 传输

默认情况下，MCP Server 使用 STDIO 作为传输机制。
不过，也支持服务器发送事件（SSE），但需要额外配置。

要启用 SSE，请将 --transport CLI 标志（或 FIREBOLT_MCP_TRANSPORT 环境变量）设置为 sse。

你也可以通过设置 --transport-sse-listen-address CLI 标志（或 FIREBOLT_MCP_TRANSPORT_SSE_LISTEN_ADDRESS 环境变量），指定服务应监听的地址。

使用 Streamable HTTP 传输

Streamable HTTP 是当前的 MCP HTTP 传输方式，网关和不支持旧版 SSE 的客户端都需要使用它。 要启用此传输方式，请将 --transport（或 FIREBOLT_MCP_TRANSPORT）设为 streamable-http。 服务器监听与 --transport-sse-listen-address 相同的地址（默认为 :8080），并在任意路径上提供 MCP 服务，例如 http://<host>:8080/mcp。

两种 HTTP 传输方式都只接受 Content-Type: application/json 的 POST 请求，因此网页无法从其他源向服务器发送 MCP 请求。 到达环回地址的服务器请求必须携带环回 Host 标头，例如 localhost:8080，否则会被拒绝并返回 403，以阻止 DNS 重绑定。 因此，同一主机上的反向代理必须转发环回 Host 标头，或连接到非环回地址。 关闭时，正在处理的请求最多有 5 秒完成。

要求大模型在连接前提供文档阅读证明

为在连接 Firebolt 并运行查询前向大模型提供更全面的上下文，默认情况下，firebolt_connect 工具 要求大模型提供 Firebolt 文档的阅读证明（通过查询 firebolt_docs_overview 工具）。

这为大模型提供了良好的起点，确保其充分了解 Firebolt 文档；但同时也可能导致响应变慢和令牌消耗增加。

要禁用此要求，请将 --skip-docs-proof CLI 布尔标志（或 FIREBOLT_MCP_SKIP_DOCS_PROOF 环境变量）设为 false。

架构

Firebolt MCP Server 实现了 Model Context Protocol，提供：

1. 工具 - 为大模型提供的特定任务能力：

   • firebolt_docs_overview：查看 Firebolt 文档概览
   • firebolt_connect：连接到 Firebolt 引擎和数据库
   • firebolt_query：对 Firebolt 执行 SQL 查询
   • firebolt_docs_search：搜索 Firebolt 文档中的任意信息

2. 资源 - 大模型可引用的数据：

   • 文档文章
   • 账户、数据库和引擎列表

3. 提示词 - 为大模型预定义的指令：

   • firebolt_expert：提示模型扮演 Firebolt 专家

开发

设置开发环境：

# Clone this repository
git clone https://github.com/firebolt-db/mcp-server.git

# Go into the repository
cd mcp-server

# Install Task (if you don't have it already)
go install github.com/go-task/task/v3/cmd/task@latest

# Update Go dependencies
task mod

# Build the application
task build

# Run the tests
task test