该项目使用@modelcontextprotocol/sdk实现了一个模型上下文协议 (MCP) 服务器，该服务器充当 BlazeSQL 自然语言查询 API 的代理。它允许兼容 MCP 的客户端（例如 Cursor、使用工具的 Claude 3、MCP Inspector 等）使用自然语言与 BlazeSQL 进行交互。
使用 MCP SDK 中的现代McpServer帮助类构建。
将 BlazeSQL 自然语言查询 API 作为名为blazesql_query的 MCP 工具公开。
使用zod对工具输入参数进行稳健验证。
通过环境变量安全地处理 API 密钥认证。
使用标准 MCP stdio 传输与客户端通信。
Related MCP server: MySQL MCP Server
该图显示了客户端使用blazesql_query工具时的交互顺序（注意：内部服务器逻辑现在使用McpServer ，与图中所示的低级处理程序相比，它简化了工具注册）：
sequenceDiagram
participant Client as MCP Client (e.g., Cursor)
participant Server as BlazeSQL MCP Server (index.ts)
participant Env as Environment (.env)
participant BlazeAPI as BlazeSQL API
Client->>Server: ListTools Request (via stdio)
Server-->>Client: ListTools Response (tools: [blazesql_query]) (via stdio)
Client->>Server: CallTool Request (blazesql_query, db_id, nl_request) (via stdio)
Server->>Env: Read BLAZE_API_KEY
Env-->>Server: BLAZE_API_KEY
Server->>BlazeAPI: POST /natural_language_query_api (apiKey, db_id, nl_request)
BlazeAPI->>BlazeAPI: Process Query (NL->SQL, Execute)
BlazeAPI-->>Server: HTTPS Response (JSON: agent_response, query, data_result OR error)
Server->>Server: Format Response (Agent response, SQL, and data into single text block)
Server-->>Client: CallTool Response (content: [{type: text, text: formattedMarkdown}]) (via stdio)
Node.js （推荐 LTS 版本）
纱线（经典或浆果）
具有 API 密钥的 BlazeSQL 帐户（API 需要 Team Advanced 订阅）。
您的 BlazeSQL 帐户中至少配置了一个数据库连接。
BlazeSQL 自然语言查询 API 文档： https://help.blazesql.com/en/article/natural-language-query-api-1fgx4au/
克隆存储库：
git clone <repository-url>
cd blaze-sql-mcp-server安装依赖项：
yarn install这将安装所有必要的依赖项，包括@modelcontextprotocol/sdk 、 dotenv和zod 。
配置环境变量：
复制示例环境文件：
cp .env.sample .env编辑.env文件：
# .env
BLAZE_API_KEY=YOUR_BLAZESQL_API_KEY_HERE将YOUR_BLAZESQL_API_KEY_HERE替换为从 BlazeSQL 帐户设置中获取的实际 API 密钥。
**构建服务器：**将 TypeScript 代码编译为 JavaScript：
yarn build**运行服务器：**执行编译后的代码：
node build/index.js服务器将启动并将消息记录到stderr （您可能会看到“API 密钥已成功加载……”等信息）。现在，服务器正在通过标准输入/输出 (stdio) 监听 MCP 客户端连接。
该服务器使用stdio传输机制。
确保服务器尚未单独运行。
运行检查器，告诉它启动你的服务器：
npx @modelcontextprotocol/inspector node build/index.jsInspector UI 将启动并自动连接到您的服务器。
导航到“工具”选项卡以与blazesql_query工具进行交互。
在终端中启动服务器：
node build/index.js**配置客户端：**在您的 MCP 客户端设置中，您需要添加自定义服务器配置。
**传输：**选择stdio 。
命令：指定用于运行服务器的具体命令。您需要提供 node 的绝对路径以及build/index.js文件的绝对路径。
示例（macOS/Linux - 根据需要调整路径）： /usr/local/bin/node /Users/your_username/path/to/blaze-sql-mcp-server/build/index.js
您可以使用终端中的which node找到节点的路径。
您可以在项目目录中使用pwd找到项目的路径。
保存配置。
客户端现在应该能够连接到您本地运行的服务器并列出/使用其工具。
blazesql_query工具一旦连接，客户端就可以调用blazesql_query工具。
工具名称： blazesql_query
参数：
db_id （字符串，必需）：BlazeSQL 帐户中目标数据库连接的 ID。您可以在 BlazeSQL Web 应用程序管理数据库连接时找到此 ID。
natural_language_request （字符串，必需）：您要执行的查询，以简单的英语编写（例如，“显示用户总数”）。 （使用zod验证输入）
示例调用（使用mcp test语法进行说明）：
call-tool blazesql_query --db_id "db_your_actual_db_id" --natural_language_request "What were the total sales last month?"**输出：**如果成功，该工具将返回包含以下内容的单个text内容块：
BlazeSQL 代理的自然语言响应。
Markdown 代码围栏内生成的 SQL 查询 ( sql ... )。
数据结果在 Markdown 代码围栏 ( json ... ) 内格式化为 JSON。
text块内的示例结构：
**Agent Response:**
The total sales last month were $12345.67.
**Generated SQL:**
```sql
SELECT sum(sales_amount) FROM sales WHERE sale_date >= date('now', '-1 month');数据结果（JSON）：
[
{
"sum(sales_amount)": 12345.67
}
]
If unsuccessful, it returns a `text` content block containing the error message from the BlazeSQL API and marks the response as an error (`isError: true`).Executes a natural language query against a specified BlazeSQL database.
| Name | Required | Description | Default |
|---|---|---|---|
| db_id | Yes | The ID of the BlazeSQL database connection to query. | |
| natural_language_request | Yes | The query expressed in natural language (e.g., 'show me total users per city'). |
| Name | Required | Description |
|---|---|---|
| query | Yes | The SQL query generated and executed by BlazeSQL. |
| data_result | Yes | The structured data returned by the query, as a map of column names to value arrays. |
| agent_response | Yes | Natural language explanation of the results from BlazeSQL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool executes queries but doesn't describe traits like error handling, performance implications, authentication needs, or rate limits. For a query execution tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized, making it easy to understand quickly. Every part of the sentence contributes to clarifying the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), 100% schema coverage, and no annotations, the description is minimally complete. It covers the basic purpose but lacks behavioral context and usage guidelines. For a query tool with no annotations, it should do more to compensate, but the output schema mitigates some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters (db_id and natural_language_request) with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as examples or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('executes') and resource ('natural language query against a specified BlazeSQL database'). It distinguishes what it does (execute natural language queries) from potential alternatives (like SQL queries), though without sibling tools, differentiation isn't needed. However, it could be more specific about the type of queries or results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, prerequisites, or exclusions. It mentions the tool's function but lacks context on appropriate scenarios, such as when natural language queries are supported or if there are limitations. With no sibling tools, this gap is less critical but still present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0blazesql_queryScored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clearly defined purpose that cannot be confused with any other tool in the set.
A single tool inherently has perfect naming consistency as there are no other tools to compare it against. The tool name follows a clear verb_noun pattern (blazesql_query) which would be consistent if more tools existed.
A single tool is generally too few for a database query server, as it lacks basic operations like listing databases, describing schemas, or managing connections. This minimal set limits functionality and forces all interactions through one interface.
The tool surface is severely incomplete for a SQL database server. While the query tool covers execution, there are obvious gaps such as no tools for schema exploration, database listing, transaction management, or data manipulation beyond queries, which will cause agent failures in many workflows.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
