Mcp Firebird

**稳定版 2.12.3 包含仅准备的优化器计划和支持目录感知的索引建议：**2.13.0-alpha.1 中的所有改进现已稳定。历史 ISO/UTC 日期仍为默认值；只有 FIREBIRD_DATE_FORMAT=wall-clock 才会启用不带时区的输出。无需升级驱动，不会自动执行索引 DDL，也没有新的安全默认设置。**需要 Node.js 20.19+。**请参阅诊断指南、发行说明和日期配置。

MCP Firebird

为 Firebird 数据库实现 Anthropic 的 MCP（模型上下文协议）。

使用示例

https://github.com/user-attachments/assets/e68e873f-f87b-4afd-874f-157086e223af

什么是 MCP Firebird？

MCP Firebird 是一项服务，为 Firebird SQL 数据库实现了 Anthropic 的模型上下文协议（MCP）。它使 Claude 等大语言模型（LLM）能够以安全且受控的方式访问、分析和处理 Firebird 数据库中的数据。

🚀 MCP 2.7+ 新功能（性能与安全性）

此服务已升级，以支持 MCP 生态系统中最新的企业级标准：

• ⚡ **连接池（零延迟）：**重复的数据库查询现在使用持久的内存连接，完全绕过握手开销，几乎瞬间执行。
• 🎯 **主动事件（触发器）：**原生集成 Firebird 的 POST_EVENT。服务实时监听数据库事件，并主动通知 AI 客户端（例如 Claude/n8n），无需持续轮询。
  • *快速示例：*让 Agent 使用 subscribe_to_event 订阅 NEW_ORDER。当 Firebird 执行 POST_EVENT 'NEW_ORDER' 时，Agent 会立即收到通知！阅读详细指南和示例。
• 🛡️ **企业托管授权（EMA）：**不想向 LLM 客户端公开实际的数据库密码（SYSDBA）？启用 EMA，即可要求传入连接提供 --api-key。服务会拦截此令牌，并在后台安全地注入真实密码。
  • *快速示例：*使用 --password "real_password" --api-key "my-secure-token" 启动服务。远程客户端使用 Authorization: Bearer my-secure-token 进行连接。数据库密码绝不会离开服务！阅读安全性详细指南。
• 🌊 **双向流式传输（Streamable HTTP / SSE）：**非常适合 n8n 或远程部署。支持通过 HTTP 实时流式传输事件和有状态会话。
  • *快速示例：*使用 TRANSPORT_TYPE=sse SSE_PORT=3003 启动服务。将客户端（例如 n8n）配置为连接到 http://YOUR_SERVER:3003/mcp。阅读详细指南。

---

🏗️ 传输模式与架构

MCP Firebird 支持多种部署架构。我们强烈建议在现代化、企业级或远程部署中使用 Streamable HTTP（SSE）。

1. [推荐] 现代传输（Streamable HTTP / SSE）

非常适合连接 n8n、云平台、远程 Agent，或与数据库不在同一台机器上的工具。

安装：

npm install -g mcp-firebird

运行服务： 设置环境变量（或 .env 文件）：

export TRANSPORT_TYPE=sse
export SSE_PORT=3003

# Real database credentials protected on the server side:
export FIREBIRD_PASSWORD=masterkey 
# Enable EMA to protect external access:
export FIREBIRD_API_KEY=my_secret_token_123

mcp-firebird --database /path/to/database.fdb --user SYSDBA

客户端连接： AI 客户端（例如 MCP Inspector、n8n）连接到 http://localhost:3003；得益于 EMA，只需提供 API KEY，无需提供实际的数据库密码。

2. [本地 / 旧版] 标准传输（STDIO）

这是经典方式，仅建议在同一台机器上个人使用（例如 Claude Desktop）。Claude 会在后台启动自己的 MCP Firebird 子进程。

主要功能

• SQL 查询：在 Firebird 数据库上执行 SQL 查询

• 架构分析：获取表、列和关系的详细信息

• 数据库元数据：检查触发器、存储过程、函数和程序包及其源代码

• 性能分析：分析查询性能并提出优化建议

• 安全性：包含 SQL 查询验证、EMA 和连接池。

• 双驱动支持：可选择简单安装（默认）或支持线路加密的原生驱动。

🔒 线路加密支持

MCP Firebird 支持两种驱动选项：

驱动	安装	线路加密	使用场景
纯 JavaScript（默认）	✅ 简单（npx）	❌ 不支持	大多数用户，快速设置
原生驱动（可选）	⚠️ 复杂（需要构建工具）	✅ 支持	企业环境，需要安全性

快速开始（默认 — 不支持线路加密）

npx -y mcp-firebird --database=/path/to/database.fdb

高级用法（支持线路加密）

⚠️ 重要警告：npx 不适用于原生驱动。必须进行全局安装。

⚠️ 重要提示：线路加密必须在 Firebird 服务（firebird.conf）上配置，而不是在客户端上配置。

服务配置（请先完成）：

# In firebird.conf on the server
WireCrypt = Required  # or Enabled

客户端安装（必须全局安装）：

# Step 1: Install build tools
# Windows: Visual Studio Build Tools (https://visualstudio.microsoft.com/downloads/)
# Linux: sudo apt-get install build-essential python3 firebird-dev
# macOS: xcode-select --install && brew install firebird

# Step 2: Install MCP Firebird globally
npm install -g mcp-firebird

# Step 3: Install native driver globally
npm install -g node-firebird-driver-native

# Step 4: Run directly (WITHOUT npx)
mcp-firebird --use-native-driver \
  --database=/path/to/database.fdb \
  --host=localhost \
  --user=SYSDBA \
  --password=masterkey

为什么不能使用 npx？ npx 从临时缓存运行程序包时，无法访问全局安装的模块，例如 node-firebird-driver-native。两个程序包都必须全局安装在同一位置。

📚 有关详细安装说明，请参阅：

• 原生驱动安装指南 — Windows/Linux/macOS 分步说明
• 线路加密指南
• 高级安装指南

手动安装

稳定版

# Global installation
npm install -g mcp-firebird

# Run the server
npx -y mcp-firebird --database /path/to/database.fdb

稳定版功能（2.12.3）：

• 支持 MCP 2026-07-28，同时兼容 2025 客户端和旧版 SSE，并共享服务入口点。
• 结构化工具契约，以及可选启用的 SQL/HTTP 安全控制。
• 安全的查询/BLOB/事务清理，以及可配置的查询时限。
• 完整的元数据描述、修正后的统计信息和已注册工具数量。
• 识别 SQL 分组/窗口语法，但不会绕过明确指定的策略。
• 仅准备查询的优化器计划，以及经过目录检查的单表索引建议（包含现有主键/复合索引）；不会自动执行 DDL。
• 默认向后兼容 ISO/UTC 日期输出；如果客户端需要，可设置 FIREBIRD_DATE_FORMAT=wall-clock 后重启 MCP 进程。请参阅日期配置。
• 请参阅 2.12.3 发行说明、2.12.2 日期兼容性修正和2.12.1 累积修复。

Alpha 版（最新功能）

# Install alpha version with latest features
npm install -g mcp-firebird@alpha

# Or use specific alpha version
npm install -g [email protected]

**alpha 2.13.0-alpha.1 的所有改进均已包含在稳定版 2.12.3 中。**请使用 mcp-firebird@latest 或固定到 [email protected]；无需安装 alpha 版即可使用 issue #45 诊断功能。alpha 标签仍指向 2.13.0-alpha.1，供现有测试人员使用。无需新增标志、升级驱动或放宽安全策略，顾问也绝不会创建索引。更新后请保留连接/安全设置并重启 MCP。请阅读诊断指南、稳定版发行说明、安全指南和日期/BLOB 兼容性说明。

有关 VSCode 和 GitHub Copilot 集成，请参阅 VSCode 集成。

基本用法

与 Claude Desktop 配合使用

1. 编辑 Claude Desktop 配置：

   code $env:AppData\Claude\claude_desktop_config.json  # Windows
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json  # macOS
   

2. 添加 MCP Firebird 配置：

   {
     "mcpServers": {
       "mcp-firebird": {
         "command": "npx",
         "args": [
           "mcp-firebird",
           "--host",
           "localhost",
           "--port",
           "3050",
           "--database",
           "C:\\path\\to\\database.fdb",
           "--user",
           "SYSDBA",
           "--password",
           "masterkey"
         ],
         "type": "stdio"
       }
     }
   }
   

3. 重启 Claude Desktop

传输配置

MCP Firebird 支持多种传输协议，以适应不同客户端需求和部署场景。

STDIO 传输（默认）

STDIO 传输是与 Claude Desktop 集成的标准方式：

{
  "mcpServers": {
    "mcp-firebird": {
      "command": "npx",
      "args": [
        "mcp-firebird",
        "--database", "C:\\path\\to\\database.fdb",
        "--user", "SYSDBA",
        "--password", "masterkey"
      ],
      "type": "stdio"
    }
  }
}

SSE 传输（服务器发送事件）

SSE 传输允许服务器作为 Web 服务运行，适用于 Web 应用和远程访问：

基本 SSE 配置

# Start SSE server on default port 3003
npx mcp-firebird --transport-type sse --database /path/to/database.fdb

# Custom port and full configuration
npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database /path/to/database.fdb \
  --host localhost \
  --port 3050 \
  --user SYSDBA \
  --password masterkey

SSE 环境变量

# Set environment variables
export TRANSPORT_TYPE=sse
export SSE_PORT=3003
export DB_HOST=localhost
export DB_PORT=3050
export DB_DATABASE=/path/to/database.fdb
export DB_USER=SYSDBA
export DB_PASSWORD=masterkey

# Start server
npx mcp-firebird

SSE 客户端连接

SSE 服务运行后，客户端可以连接到：

• SSE 端点：http://localhost:3003/sse
• 消息端点：http://localhost:3003/messages
• 健康检查：http://localhost:3003/health

Streamable HTTP 传输（现代）

最新的 MCP 协议，支持双向通信：

# Start with Streamable HTTP
npx mcp-firebird --transport-type http --http-port 3003 --database /path/to/database.fdb

统一传输（推荐）

同时支持 SSE 和 Streamable HTTP 协议，并可自动检测：

# Start unified server (supports both SSE and Streamable HTTP)
npx mcp-firebird --transport-type unified --http-port 3003 --database /path/to/database.fdb

统一服务端点

• SSE（旧版）：http://localhost:3003/sse
• Streamable HTTP（现代）：http://localhost:3003/mcp
• 协议自动检测：http://localhost:3003/mcp
• 健康检查：http://localhost:3003/health

配置示例

开发环境设置（SSE）

npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database ./dev-database.fdb \
  --user SYSDBA \
  --password masterkey

生产环境设置（统一）

npx mcp-firebird \
  --transport-type unified \
  --http-port 3003 \
  --database /var/lib/firebird/production.fdb \
  --host db-server \
  --port 3050 \
  --user APP_USER \
  --password $DB_PASSWORD

使用 SSE 的 Docker

docker run -d \
  --name mcp-firebird \
  -p 3003:3003 \
  -e TRANSPORT_TYPE=sse \
  -e SSE_PORT=3003 \
  -e DB_DATABASE=/data/database.fdb \
  -v /path/to/database:/data \
  purodelhi/mcp-firebird:latest

高级 SSE 配置

会话管理

配置会话超时和限制：

# Environment variables for session management
export SSE_SESSION_TIMEOUT_MS=1800000    # 30 minutes
export MAX_SESSIONS=1000                 # Maximum concurrent sessions
export SESSION_CLEANUP_INTERVAL_MS=60000 # Cleanup every minute

npx mcp-firebird --transport-type sse

CORS 配置

对于浏览器应用，请将访问权限限制为一个或多个以逗号分隔的来源。默认值为 *，且禁用浏览器凭据，因此现有的 STDIO 和 Bearer-token MCP 客户端仍可兼容：

# Allow specific browser origins
export MCP_ALLOWED_ORIGIN="https://myapp.com,https://localhost:3000"

npx mcp-firebird --transport-type sse

稳定版 2.12.3 保留了 2.11/2.12 的安全改进和默认的历史日期输出，并新增了安全的查询诊断功能。 使用 npm install -g mcp-firebird@latest 安装，或固定为 [email protected]。显式配置的策略仍会强制执行；请查看迁移指南和发布说明。日期格式选择是独立的进程环境设置，不属于安全策略字段。

默认情况下，原始 SQL 写入处于禁用状态。2.11.0 保留了用于写入（包括 DDL）的历史开关 ALLOW_RAW_SQL=true，无需新标志。该开关绝不会绕过显式配置的操作／表／行／脱敏／角色限制以及 sql.allowDDL=false。有关选择加入的控制项和结构化 get-table-data 过滤器格式，请参阅安全指南。

可使用 --security-config /absolute/path/security-config.json 或环境变量 FIREBIRD_SECURITY_CONFIG 加载自定义安全文件。SECURITY_CONFIG 和 SECURITY_CONFIG_PATH 是按此顺序使用的备用别名；CLI 选项优先于环境变量。使用如下 JSON 对象：{"security":{"allowedTables":["EMPLOYEES"],"allowedOperations":["SELECT"],"maxRows":100}}。也支持受信任的 CommonJS 文件。更改策略后请重启，并检查是否出现 Loaded security configuration from ...。从 2.11.0-alpha.2 开始，选定的文件无效或缺失时会停止初始化，而不是静默应用默认值。请参阅安全指南。

从 2.11.0-alpha.1 开始，可将同一 JSON 字符串设置为 FIREBIRD_SECURITY_JSON，无需文件即可配置安全设置。也支持 SQL 选项。在 2.11.0-alpha.3 中，高级限制需选择启用： 不会隐式启用资源配额、截止时间、目录拒绝或新的例程限制。只设置所需的控制项；例如，{"security":{"maxRows":100}} 仅启用该行数上限。显式策略都会强制执行，包括旧版未强制执行的选项。文件路径优先级更高。只有受信任的管理员／启动器可以设置此变量；HTTP/SSE 客户端无法更改它。内联 JSON 限制为 64 KiB（UTF-8），会经过验证但不会执行代码，加载器也不会记录其内容。无效策略会导致初始化失败。取消设置该变量即可禁用此配置来源；更改后请重启。请查看迁移通知、配置示例和实现审查。

SSL/TLS 支持

对于生产部署，请使用 nginx 等反向代理：

server {
    listen 443 ssl;
    server_name mcp-firebird.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3003;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

故障排除

Firebird 连接问题

1. Wire 加密不兼容（Firebird 3.0+） ⚠️ 严重

   错误：Incompatible wire encryption levels requested on client and server

   重要：node-firebird 库不支持 Firebird 3.0+ 的 Wire 加密。--wire-crypt 参数不起作用。

   唯一解决方案：必须在 Firebird 服务端禁用 Wire 加密：

   对于 Firebird 3.0，在 firebird.conf 中添加：

   WireCrypt = Disabled
   AuthServer = Srp, Legacy_Auth
   

   对于 Firebird 4.0+，在 firebird.conf 中添加：

   WireCrypt = Disabled
   AuthServer = Srp256, Srp, Legacy_Auth
   

   对于 Firebird 5.0 Docker：

   environment:
     FIREBIRD_CONF_WireCrypt: Disabled
     FIREBIRD_CONF_AuthServer: Srp256, Srp
   

   如果无法更改服务端配置，请参阅Wire 加密限制了解替代方案。

2. Linux/Unix 上的数据库路径问题

   问题：远程连接字符串或 Unix 路径无法使用

   解决方案：此问题已在 v2.4.0-alpha.1+ 中修复。以下路径现在均可正常使用：

   • 远程：server:/path/to/database.fdb
   • Unix 绝对路径：/var/lib/firebird/database.fdb
   • 基于 IP 的路径：192.168.1.100:/data/db.fdb

3. Windows 上混合大小写路径导致的 I/O 错误

   错误：I/O error during CreateFile (open) operation

   问题：数据库路径包含大小写混合的字符（例如，C:\MyData\database.fdb）时会导致错误

   解决方法：

   • 使用全大写路径：C:\MYDATA\DATABASE.FDB
   • 使用正斜杠：C:/MyData/database.fdb
   • 有关详细信息，请参阅 Wire 加密修复文档

SSE 连接问题

1. 连接被拒绝

   # Check if server is running
   curl http://localhost:3003/health
   
   # Check port availability
   netstat -an | grep 3003
   

2. 会话超时

   # Increase session timeout
   export SSE_SESSION_TIMEOUT_MS=3600000  # 1 hour
   

3. CORS 错误

   # Allow all origins (development only)
   export CORS_ORIGIN="*"
   

4. 内存问题

   # Reduce max sessions
   export MAX_SESSIONS=100
   
   # Enable more frequent cleanup
   export SESSION_CLEANUP_INTERVAL_MS=30000
   

5. JSON 解析问题（已在 v2.3.0-alpha.1+ 中修复）

   # If experiencing "Invalid message: [object Object]" errors,
   # upgrade to the latest alpha version:
   npm install mcp-firebird@alpha
   
   # Or use the latest alpha directly:
   npx mcp-firebird@alpha --transport-type sse
   

   注意：在 2.3.0-alpha.1 之前的版本中，向 /messages 端点发送的 POST 请求存在错误，无法正确解析 JSON 请求体。此问题已修复，并改进了对 application/json 和 text/plain 内容类型的中间件处理。

监控和日志记录

# Enable debug logging
export LOG_LEVEL=debug

# Monitor server health
curl http://localhost:3003/health | jq

# Check active sessions
curl http://localhost:3003/health | jq '.sessions'

文档

如需了解更多详细信息，请查看以下文档：

入门

• 完整安装指南
• 配置选项
• 可用工具
• 数据库元数据工具 - 检查触发器、存储过程、函数和包
• 资源、工具和提示词参考 - MCP 全部功能的完整指南

传输协议

• 传输配置

集成指南

• VSCode 集成
• Docker 配置
• 在不同语言中使用

高级主题

• 安全
• 故障排除
• Wire 加密修复 - Firebird 3.0+ 兼容性和 Linux 路径修复

示例和用例

• 用例和示例

支持项目

捐赠

如果 MCP Firebird 对您的工作或项目有所帮助，请考虑捐赠以支持其开发。您的捐助有助于维护和改进此工具。

• GitHub Sponsors：赞助 @PuroDelphi
• PayPal：通过 PayPal 捐赠

聘用我们的 AI Agent

支持此项目的另一种好方式是通过 Asistentes Autónomos 聘用我们的 AI Agent。我们为各种业务需求提供专业的 AI 助手，帮助您自动执行任务并提高工作效率。

优先支持

⭐ 捐赠者、赞助商和客户在处理问题、功能请求和实施指导时可获得优先支持与协助。我们会尽力帮助所有用户，但为项目提供资金支持的用户将获得更快的响应和专属协助。

非常感谢您的支持，这有助于确保 MCP Firebird 持续开发！

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。