MCP 服务

SQLBot 支持通过 MCP 进行服务端图表渲染与智能问数处理。

1 服务配置

SQLBot MCP Server 默认监听端口为 8001，使用 SSE 协议进行通信。基本配置如下：

{
   "sqlbot_mcp": {
       "url": "http://<your-server-ip>:8001/mcp", // 将 IP 替换为部署机器的地址
       "transport": "sse"
    }
}

SQLBot 运行方式不同，对应的 MCP 参数 SERVER_IMAGE_HOST 的配置方式不同，注意该参数中的 IP 是 SQLBot 服务器的 IP 地址，端口是 MCP 服务的端口，默认情况下，服务端口是 8001（切记不是 3000 端口）。另外，注意跨域 、https 、http协议安全等可能导致图片无法加载。

• 安装包安装方式
  • 确认 SQLBot 的 .env 配置文件(默认位置 /opt/sqlbot/.env)中的 SQLBOT_SERVER_IMAGE_HOST：

图 1 SQLBot MCP 环境

• 确认 SQLBot 运行配置文件(默认位置 /opt/sqlbot/conf/sqlbot.conf)中的 SERVER_IMAGE_HOST：

图 2 SQLBot MCP 配置

若参数并非实际的 IP 和端口，请修改完上述两个配置参数后，重启一下 SQLBot 服务：

sctl restart

• 1Panel 运行方式
  • 确认相关参数是否正确，若与实际情况部分，请修改后重启 SQLBot 服务：

图 3 SQLBot MCP 1Panel

• docker 一键运行方式
  • 若之前运行方式没有加上 SERVER_IMAGE_HOST 参数，或者参数值不对，则停止 SQLBot 服务并删除容器
  • 修改 MCP 运行参数 SERVER_IMAGE_HOST，注意将 IP 和端口替换成自己的实际 IP 和端口：

    docker run -d \
        --name sqlbot \
        --restart unless-stopped \
        -p 8000:8000 \
        -p 8001:8001 \
        -e SERVER_IMAGE_HOST=http://47.92.75.231:8001/images/ \
        -v data/sqlbot/excel:/opt/sqlbot/data/excel \
        -v ./data/sqlbot/file:/opt/sqlbot/data/file \
        -v data/sqlbot/images:/opt/sqlbot/images \
        -v data/sqlbot/logs:/opt/sqlbot/logs \
        -v data/postgresql:/var/lib/postgresql/data \
        --privileged=true \
        dataease/sqlbot

• docker-compose 一键运行方式
  • 若之前运行方式没有加上 SERVER_IMAGE_HOST 参数，或者参数值不对，则停止 SQLBot 服务并删除容器
  • 修改 docker-compose.yml 文件中的 MCP 参数 SERVER_IMAGE_HOST，注意将 IP 和端口替换成自己的实际 IP 和端口：

    services:
      sqlbot:
        image: dataease/sqlbot:v1.1.0
        container_name: sqlbot
        restart: always
        networks:
          - sqlbot-network
        ports:
          - 8000:8000
          - 8001:8001
        environment:
        # Database configuration
          POSTGRES_SERVER: localhost
          POSTGRES_PORT: 5432
          POSTGRES_DB: sqlbot
          POSTGRES_USER: root
          POSTGRES_PASSWORD: Password123@pg
          # Project basic settings
          PROJECT_NAME: "SQLBot"
          DEFAULT_PWD: "SQLBot@123456"
          # MCP settings
          SERVER_IMAGE_HOST: http://47.92.75.231:8001/images/
          # Auth & Security
          SECRET_KEY: y5txe1mRmS_JpOrUzFzHEu-kIQn3lf7ll0AOv9DQh0s
          # CORS settings
          BACKEND_CORS_ORIGINS: "http://localhost,http://localhost:5173,https://localhost,https://localhost:5173"
          # Logging
          LOG_LEVEL: "INFO"
          SQL_DEBUG: False
        volumes:
          - data/sqlbot/excel:/opt/sqlbot/data/excel
          - data/sqlbot/file:/opt/sqlbot/data/file
          - data/sqlbot/images:/opt/sqlbot/images
          - data/sqlbot/logs:/opt/sqlbot/logs
          - data/postgresql:/var/lib/postgresql/data
    
    networks:
      sqlbot-network:

2 MCP 工具说明

SQLBot 的 MCP Server 对外提供以下工具：

• access_token：登录获取身份凭证
• mcp_start：创建问数会话（可指定工作空间）
• mcp_question：提交问题并返回 SQL、数据与图表
• mcp_ws_list、mcp_datasource_list、mcp_model_list：分别用于获取工作空间、数据源与可用模型列表

1.10.0 及以后，登录与建会话已拆分：access_token 负责鉴权，mcp_start 负责创建会话并确定工作空间。mcp_question 不再接收 oid。

2.1 access_token 工具

用于登录 SQLBot，获取后续调用所需的 access_token。推荐作为对接流程的第一步。

表 1 access_token 工具参数

参数名	类型	必填	说明
username	string	是	SQLBot 用户名
password	string	是	SQLBot 用户密码

返回示例：

{
    "code": 0,
    "data": {
        "access_token": "<JWT_TOKEN>"
    },
    "msg": null
}

• access_token：身份验证使用，后续 mcp_start、mcp_question 等工具均需传入。

2.2 mcp_start 工具

用于创建一次智能问数会话，返回 chat_id。会话所属工作空间在此阶段确定，后续同一 chat_id 下的问数将沿用该组织，无需再传 oid。

鉴权方式二选一：

• 推荐：先调用 access_token 获取 token，再传入 token（及可选 oid）创建会话
• 兼容：直接传入 username、password，mcp_start 会同时完成登录并创建会话

表 2 mcp_start 工具参数

参数名	类型	必填	说明
token	string	否	access_token 返回的凭证；与 username / password 二选一
username	string	否	SQLBot 用户名；未传 token 时必填
password	string	否	SQLBot 用户密码；未传 token 时必填
oid	string	否	组织（工作空间）ID；不传则使用用户最后一次登录 SQLBot 时所使用的组织 ID。用户必须属于该工作空间，否则会报错

返回示例：

{
    "code": 0,
    "data": {
        "access_token": "<JWT_TOKEN>",
        "chat_id": 1330
    },
    "msg": null
}

• access_token：当前会话使用的身份凭证（传入 token 时原样返回；传入账号密码时为新签发的凭证）
• chat_id：唯一对话上下文 ID，后续问数保持一致可维持上下文状态

2.3 mcp_question 工具

用于在已初始化的问数上下文中提交用户问题，并返回对应 SQL、可视化结果及图表图片地址。

表 3 mcp_question 工具参数

参数名	类型	必填	默认值	说明
token	string	是	—	access_token 或 mcp_start 返回的 access_token
chat_id	integer	是	—	mcp_start 返回的 chat_id
question	string	是	—	用户的自然语言提问
stream	boolean	否	true	是否流式输出。true 时以 Markdown 流式返回；false 时返回 JSON 对象
lang	string	否	zh-CN	响应语言，可选值：zh-CN、zh-TW、en、ko-KR
datasource_id	integer / string	否	null	数据源 ID，仅当当前对话尚未确定数据源时有效
custom_model	integer / string	否	null	模型 ID，可通过 mcp_model_list 获取；不传则使用默认模型
return_img	boolean	否	true	是否返回图表图片。false 时仅返回数据，不生成图表图片

1.10.0 及以后，mcp_question 已移除 oid 参数。工作空间请在调用 mcp_start 时通过 oid 指定。

返回结果示例（Markdown 格式）：

```sql SELECT "s"."区域", COUNT(*) AS "count" FROM "public"."Sheet1_c27345b66e" "s" GROUP BY "s"."区域" ORDER BY "s"."区域" ``` | 区域 | 数量 | |:-----|-----:| | 东区 | 269 | | 北区 | 321 | | 南区 | 275 | | | 4 | ### generated chart picture ![column](https://sqlbot.fit2cloud.cn/images/c_1330_r_2976.png)

2.4 mcp_ws_list 工具

用于获取当前用户可访问的工作空间（组织）列表，便于在创建会话前选择目标组织。

参数名	说明
token	access_token 返回的 access_token

返回示例：

{ "code": 0, "data": [ { "id": 1, "name": "默认工作空间" } ], "msg": null }

2.5 mcp_datasource_list 工具

用于获取指定组织下可用的数据源列表，便于在问数时通过 datasource_id 指定数据源。

参数名	说明
token	access_token 返回的 access_token
oid	可选，组织 ID；不传则使用用户最后一次登录时所使用的组织 ID

返回示例：

{ "code": 0, "data": [ { "id": 10, "name": "销售数据源", "type": "mysql", ... } ], "msg": null }

2.6 mcp_model_list 工具

用于获取指定工作空间下可用的 AI 模型列表，便于在问数时通过 custom_model 指定模型。1.10.1 及以后可用。

参数名	类型	必填	说明
oid	string / integer	是	组织（工作空间）ID

返回示例：

{
    "code": 0,
    "data": [
        { "id": 1, "name": "默认模型", "default_model": true, "supplier": 1 },
        { "id": 2, "name": "业务模型", "default_model": false, "supplier": 2 }
    ],
    "msg": null
}

• id：模型 ID，作为 mcp_question 的 custom_model 传入
• name：模型名称
• default_model：是否为默认模型
• supplier：模型供应商标识

2.7 对接流程说明

对接步骤：

• 步骤 1：调用 access_token，传入 username、password，获取 access_token。
• 步骤 2（可选）：调用 mcp_ws_list 获取工作空间列表；调用 mcp_datasource_list、mcp_model_list 获取数据源与模型列表。
• 步骤 3：调用 mcp_start，传入 token 与可选 oid，创建会话并获取 chat_id。
• 步骤 4：调用 mcp_question，传入 token、chat_id 与用户问题 question；可按需指定 datasource_id、custom_model。

建议：

• 每次调用 mcp_start 会生成新的 chat_id；
• 对话过程中保持 chat_id 一致，才能维持上下文；
• 建议缓存 access_token 和 chat_id：一次对话只登录一次、只创建一次会话；
• 指定工作空间必须在 mcp_start 阶段传入 oid，在 mcp_question 中传 oid 不会生效。

3 使用示例

1.10.0 及以后，推荐流程为：access_token（登录）→ mcp_start（创建会话，可传 oid）→ mcp_question（问数）。下文编排类示例按该流程配置。

3.1 MaxKB 集成示例

下载完整示例文件

步骤⼀： 创建或进入一个高级编排类型的应用。

步骤二： 在「基本信息」里添加两个用户输入，分别是 username 和 password，添加两个会话变量，分别是 sqlbot_token 和 sqlbot_chat_id。如需指定工作空间，可再增加用户输入 oid。

步骤三： 添加条件判断，在开始节点后添加条件分支（IF）。判断条件：会话变量 > sqlbot_token 是否为空。为空：执行登录并创建会话（步骤四至步骤八）；不为空：跳过登录与建会话，直接进入问数调用（步骤九）。

步骤四： 配置 MCP 登录：

添加 MCP 调用节点

• MCP Server Config 服务配置：

  {
      "sqlbot_mcp": {
          "url": "http://<SQLBot_MCP_IP>:8001/mcp",
          "transport": "sse"
      }
  }

• 工具配置： 单击「获取工具」，选择 access_token
• 工具参数配置： username 从全局变量里选择 username；password 从全局变量里选择 password。

步骤五： 解析登录结果：

MCP 调用后添加「自定义工具」。access_token 的返回值通常是 JSON 字符串组成的列表，需要先取出首个元素再解析。添加输入参数，将 MCP 调用结果赋值给参数 response。工具内容：

import json

def extract_token(response):
    # MCP result 是 ["{json}"] 这种列表
    if isinstance(response, list):
        response = response[0]
    if isinstance(response, str):
        response = json.loads(response)
    return response["data"]["access_token"]

将该自定义工具的输出作为下一步 mcp_start 的 token 参数。

步骤六： 创建问数会话 添加 MCP 调用节点，调用 mcp_start：

• MCP Server Config 服务配置与步骤四相同
• 工具配置：单击「获取工具」，选择 mcp_start
• 工具参数配置：
  • token：选择上一步自定义工具 extract_token 的输出
  • username：选择开始节点的 username
  • password：选择开始节点的 password
  • oid：如需指定工作空间，绑定到开始节点的 oid 输入

步骤七： 解析会话结果 mcp_start 返回的 JSON 同时包含 access_token 和 chat_id。添加「自定义工具」，输入参数将 MCP 调用结果赋值给 arg1，工具内容：

import json
def main1(arg1):
    json_obj = json.loads(arg1[0])
    return {"token":json_obj["data"]["access_token"], "chat_id":json_obj["data"]["chat_id"]}

步骤八： 变量赋值 添加变量赋值节点，将上一步输出的 token 存储为会话变量 sqlbot_token，将 chat_id 存储为会话变量 sqlbot_chat_id。一次对话只登录一次、只创建一次会话。

步骤九： 问数 MCP 调用配置 条件分支的两条路径在此处汇合。添加 MCP 调用节点，配置问数调用

• MCP Server Config 服务配置：

{
    "sqlbot_mcp": {
        "url": "http://<SQLBot_MCP_IP>:8001/mcp",
        "transport": "sse"
    }
}

• 工具配置： 单击「获取工具」，选择 mcp_question
• 工具参数配置： question 选择「开始 > 用户问题」，chat_id 选择「会话变量 > sqlbot_chat_id」，token 选择「会话变量 > sqlbot_token」。可按需绑定 datasource_id、custom_model。

步骤十： 清洗问数结果 mcp_question 的返回值通常是列表，且文本中可能包含零宽空格（\u200b）。添加「自定义工具」，将 MCP 调用结果赋值给参数 input_text，工具内容：

def main(input_text):
    # input_text 是一个 list
    result = []
    for item in input_text:
        result.append(item.replace('\u200b', ''))
    return '\n'.join(result)

步骤十一：在流程末尾添加指定回复节点，将上一步清洗后的结果作为回复内容。输入有效的 username 与 password 测试登录及 MCP 功能调用是否正常。

图 4 SQLBot Make MCP

3.2 Dify 集成示例

下载完整示例文件

步骤⼀： 进入需要配置的工作空间，创建一个 Chatflow 类型的应用；

步骤二： 在开始节点中定义输入变量： username（必填） 、password（必填）；

步骤三： 添加会话变量 chat_id（Number）和 access_token（String）；

步骤四： 添加条件分支，在开始节点后添加条件分支（IF）。判断条件：access_token 是否为空。为空：执行登录逻辑，调用 MCP 工具 access_token；

步骤五： 在 marketplace 中搜索 “MCP”，添加工具 “MCP SSE / StreamableHTTP”，添加 MCP 调用。工具名称为 access_token

配置 MCP 工具参数：

• 输入参数：

{
"username": "{{开始节点的username}}",
"password": "{{开始节点的password}}"
}

• MCP 服务配置：

{
    "sqlbot_mcp": {
        "url": "http://<SQLBot_MCP_IP>:8001/mcp",
        "transport": "sse"
    }
}

步骤六：解析 access_token

• 添加输入变量 “arg1”，选择 “access_token 的 text”

• 添加 代码执行 节点（Python）来解析 JSON：

import json

def main(arg1: str) -> dict:
json_obj = json.loads(arg1)
return {
"access_token": json_obj["data"]["access_token"]
}

• 添加输出变量 access_token（String）

步骤七： 变量赋值

添加变量赋值节点，将 access_token 存储为会话变量。

步骤八： 创建问数会话

调用 MCP 工具 mcp_start，工具名称为 mcp_start

• 参数设置（如需指定工作空间，增加 oid）

  {
      "token":"{{#conversation.access_token#}}"
  }

• MCP 服务配置与步骤五相同

步骤九：解析 chat_id

• 添加输入变量 “arg1”，选择 “mcp_start 的 text”
• 添加 代码执行 节点（Python）：

import json

def main(arg1: str) -> dict:
json_obj = json.loads(arg1)
return {
"chat_id": json_obj["data"]["chat_id"]
}

• 添加输出变量 chat_id（Number），再通过变量赋值写入会话变量

步骤十： 执行 MCP 问数调用

调用 MCP 工具 mcp_question，工具名称为 mcp_question

• 参数设置

  {
      "chat_id":{{#conversation.chat_id#}}, 
      "question":"{{#sys.query#}}",
      "token":"{{#conversation.access_token#}}"
  }

• 执行后续 MCP 业务调用

  {
      "sqlbot_mcp": {
          "url": "http://<SQLBot_MCP_IP>:8001/mcp",
          "transport": "sse"
      }
  }

步骤十一：在流程末尾添加回答节点，将 MCP 返回的内容回复给用户。输入有效的 username 与 password 测试登录及 MCP 功能调用是否正常。

图 5 SQLBot Dify MCP

3.3 Coze 集成示例

方式一：

步骤⼀：进入工作空间，创建一个新的应用或进入已有应用。

步骤二：在开始节点中设置输入变量： username（必填） 、password（必填）；

步骤三：在开始节点后添加文本处理节点（文本处理节点用于字符串拼接），传入 username 和 password，编辑表达式如下：

{"username":"{{String1}}","password":"{{String2}}"}

步骤四：调用 MCP 工具 access_token。在文本处理节点后添加 MCP SSE Client 工具节点，设置如下：

• 输入变量：文本处理节点输出

• 工具名称：access_token

• SSE URL：http://SQLBot_MCP_IP:8001/mcp

步骤五：MCP 将返回包含 access_token 的 JSON。添加 Python 代码节点解析：

import json

def main(args) -> dict:
params = args.params
input_json_str = params.get('input')
json_obj = json.loads(input_json_str)
data = json_obj.get('data')
return {
 "access_token": data.get('access_token')
}

设置输出：返回 access_token（String）。

步骤六：添加文本处理节点，将 token 与可选 oid 拼接后调用 mcp_start，表达式如下：

{"token":"{{String1}}"}

再添加 MCP SSE Client 工具节点：工具名称 mcp_start，SSE URL 与步骤四相同。如需指定工作空间，在 JSON 中增加 "oid":"\{\{工作空间ID\}\}"。

步骤七：解析 mcp_start 返回的 chat_id。添加 Python 代码节点：

import json

def main(args) -> dict:
params = args.params
input_json_str = params.get('input')
json_obj = json.loads(input_json_str)
data = json_obj.get('data')
return {
 "chat_id": data.get('chat_id')
}

设置输出：返回 chat_id（String）。

步骤八：添加文本处理节点，将 access_token、chat_id 与开始节点的 question 变量进行拼接，表达式如下：

{"token":"{{String1}}","chat_id":"{{String2}}","question":"{{String3}}"}

步骤九：调用 MCP 工具 mcp_question。在文本处理节点后添加 MCP SSE Client 工具节点，设置如下：

• 输入变量：文本处理节点输出

• 工具名称：mcp_question

• SSE URL：http://<host>:8001/mcp

步骤十：在结束节点将 MCP 返回的内容回复给用户。输入有效的 username、password 以及 question，即可测试登录及 MCP 功能调用是否正常。

图 6 Coze 1

图 7 Coze 2

方式二：

步骤⼀：进入工作空间，创建一个新的应用或进入已有应用。

步骤二：定义输入变量。在开始节点中设置以下必填输入变量：username、password、question。

步骤三：添加大模型节点，选择合适的模型。添加技能：MCP Compatible/call_tool。配置输入参数如下：

{
"sqlbot_mcp": {
"uri": "http://<SQLBot_MCP_IP>:8001/mcp",
"transport": "sse"
}
}

传入开始节点的 username 、 password 以及 question 参数，添加系统提示词。提示词参考：

# 回答要求：
按需调用 access_token、mcp_start 和 mcp_question 工具获取信息回答问题。

登录账号密码：
{{username}}
{{password}}

工具调用逻辑：
首先调用 access_token 工具，传入 username、password，获取 access_token，帮我记住该参数，之后不要重复调用 access_token；然后调用 mcp_start 工具，传入 token（指定工作空间时再传 oid），获取 chat_id，之后不要重复调用 mcp_start；再调用 mcp_question 工具，其中 token 来自 access_token，chat_id 来自 mcp_start，question 是用户提问。

# 用户提问：
{{question}}

# 输出要求
- 如果 mcp_question 中有图片，请直接返回图片
- 请将 mcp_question 的执行结果中的数据、SQL以及图片内容展示
- 请将 mcp_question 的执行过程在结尾进行总结

# 限制
- 不要输出MCP详细执行过程
- 生成内容不要放在 mcp_question 执行过程中
- 严格按照输出要求输出内容，不要输出MCP调用过程

步骤四：添加结束节点，将大模型返回的内容回复给用户。输入有效的 username 与 password 以及输入 question，测试登录及 MCP 功能调用是否正常。

图 8 Coze 3

图 9 Coze 4

3.4 n8n 集成示例

方式一：

步骤⼀：进入 My project，创建或进入一个 workflow。

步骤二：添加表单触发器节点，节点中定义表单元素： username（必填） 、password（必填）、question（必填）。

步骤三：添加 AI Agent 节点，编辑提示词，提示词参考如下：

# 回答要求：
按需调用 access_token、mcp_start 和 mcp_question 工具获取信息回答问题。

登录账号密码：
username:{{ $json.username }}
password:{{ $json.password }}

工具调用逻辑：
首先调用 access_token 工具，传入 username、password，获取 access_token，帮我记住该参数，之后不要重复调用 access_token；然后调用 mcp_start 工具，传入 token（指定工作空间时再传 oid），获取 chat_id，之后不要重复调用 mcp_start；再调用 mcp_question 工具，其中 token 来自 access_token，chat_id 来自 mcp_start，question 是用户提问。

# 用户提问：
{{ $json.question }}

# 输出要求
- 如果 mcp_question 中有图片，请直接返回图片
- 请将 mcp_question 的执行结果中的数据、SQL以及图片内容展示
- 请将 mcp_question 的执行过程在结尾进行总结

# 限制
- 不要输出MCP详细执行过程
- 生成内容不要放在 mcp_question 执行过程中
- 严格按照输出要求输出内容，不要输出MCP调用过程

步骤四：添加 model 节点，配置 AI 模型，填写 api key。

步骤五：调用 MCP Clien 工具，在 Parameters 的 Endpoint 填入 SQLBot 填入 MCP 服务地址：http://SQLBot_MCP_IP:8001/mcp。

点击【Execute workflow】输入有效的 username 与 password 以及输入 question，测试登录及 MCP 功能调用是否正常。

图 10 n8n 1

图 11 n8n 2

方式二：

步骤⼀：进入 My project，创建或进入一个 workflow。

步骤二：添加聊天触发器节点。

步骤三：添加 AI Agent 节点，编辑提示词，提示词参考如下：

# 回答要求：
按需调用 access_token、mcp_start 和 mcp_question 工具获取信息回答问题。

登录账号密码：
username:admin
password:SQLBot@123456

工具调用逻辑：
首先调用 access_token 工具，传入 username、password，获取 access_token，帮我记住该参数，之后不要重复调用 access_token；然后调用 mcp_start 工具，传入 token（指定工作空间时再传 oid），获取 chat_id，之后不要重复调用 mcp_start；再调用 mcp_question 工具，其中 token 来自 access_token，chat_id 来自 mcp_start，question 是用户提问。

# 用户提问：
{{ $json.chatInput }}

# 输出要求
- 如果 mcp_question 中有图片，请直接返回图片
- 请将 mcp_question 的执行结果中的数据、SQL以及图片内容展示
- 请将 mcp_question 的执行过程在结尾进行总结

# 限制
- 不要输出MCP详细执行过程
- 生成内容不要放在 mcp_question 执行过程中
- 严格按照输出要求输出内容，不要输出MCP调用过程

步骤四：添加 model 节点，配置 AI 模型，填写 api key。

步骤五：调用 MCP Clien 工具，在 Parameters 的 Endpoint 填入 SQLBot 填入 MCP 服务地址：http://SQLBot_MCP_IP:8001/mcp。

点击【Execute workflow】，测试登录及 MCP 功能调用是否正常。

图 12 n8n 3

图 13 n8n 4