[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/1cb2bb07-00f4-4579-b535-1b9de9b451e9)

> **Stable 2.12.3 includes prepare-only optimizer plans and catalog-aware index advice:** all improvements from 2.13.0-alpha.1 are now stable. Historical ISO/UTC dates remain the default; only `FIREBIRD_DATE_FORMAT=wall-clock` enables zone-free output. No driver upgrade, automatic index DDL or new security defaults. **Node.js 20.19+ is required.** See the [diagnostics guide](docs/query-diagnostics.md), [release notes](docs/releases/2.12.3.md) and [date configuration](docs/blob-date-compatibility.md).

# MCP Firebird

Implementation of Anthropic's MCP (Model Context Protocol) for Firebird databases.

## Example Usage

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

## What is MCP Firebird?

MCP Firebird is a server that implements Anthropic's [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model_context_protocol) for [Firebird SQL databases](https://firebirdsql.org/). It allows Large Language Models (LLMs) like Claude to access, analyze, and manipulate data in Firebird databases securely and in a controlled manner.

## 🚀 What's New in MCP 2.7+ (Performance & Security)

This server has been upgraded to support the latest enterprise standards in the MCP ecosystem:

- ⚡ **Connection Pooling (Zero Latency):** Repetitive database queries now use persistent in-memory connections, completely bypassing handshake overhead and executing almost instantly.
- 🎯 **Proactive Events (Triggers):** Native integration with Firebird's `POST_EVENT`. The server listens to database events in real-time and proactively notifies the AI client (e.g., Claude/n8n) without requiring continuous polling.
  - *Quick Example:* Ask your agent to `subscribe_to_event` with `NEW_ORDER`. When Firebird runs `POST_EVENT 'NEW_ORDER'`, your agent gets instantly notified! [Read detailed guide and examples](docs/proactive-events.en.md).
- 🛡️ **Enterprise-Managed Authorization (EMA):** Don't want to expose your actual database password (`SYSDBA`) to the LLM client? Enable EMA to require an `--api-key` on incoming connections. The server intercepts this token and injects the real password securely under the hood.
  - *Quick Example:* Start the server with `--password "real_password" --api-key "my-secure-token"`. The remote client connects using `Authorization: Bearer my-secure-token`. The database password never leaves the server! [Read detailed guide in Security](docs/security.md).
- 🌊 **Bidirectional Streaming (Streamable HTTP / SSE):** Perfect for n8n or remote deployments. Provides real-time event streaming and stateful sessions across HTTP.
  - *Quick Example:* Start the server with `TRANSPORT_TYPE=sse SSE_PORT=3003`. Configure your client (like n8n) to connect to `http://YOUR_SERVER:3003/mcp`. [Read detailed guide](docs/transport-types.md).

---

## 🏗️ Transport Modes & Architecture

MCP Firebird supports multiple deployment architectures. We highly recommend using **Streamable HTTP (SSE)** for modern, enterprise, or remote deployments.

### 1. [RECOMMENDED] Modern Transport (Streamable HTTP / SSE)
Ideal for connecting n8n, cloud platforms, remote agents, or tools that don't reside on the same machine as your database.

**Installation:**
```bash
npm install -g mcp-firebird
```

**Run the Server:**
Set up your environment variables (or `.env` file):
```bash
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
```

**Client Connection:**
Your AI client (e.g., MCP Inspector, n8n) connects to `http://localhost:3003` and, thanks to EMA, **only needs to provide the API KEY** instead of the actual database password.

### 2. [LOCAL / LEGACY] Standard Transport (STDIO)
This is the classic method recommended only for personal use on the same machine (e.g., Claude Desktop). Claude spawns its own MCP Firebird subprocess in the background.

## Key Features

- **SQL Queries**: Execute SQL queries on Firebird databases
- **Schema Analysis**: Get detailed information about tables, columns, and relationships
- **Database Metadata**: Inspect triggers, stored procedures, functions, and packages with source code

- **Performance Analysis**: Analyze query performance and suggest optimizations
- **Security**: Includes SQL query validation, EMA, and Connection Pooling.
- **Dual Driver Support**: Choose between simple installation (default) or native driver with wire encryption support.



## 🔒 Wire Encryption Support

MCP Firebird supports **two driver options**:

| Driver | Installation | Wire Encryption | Use Case |
|--------|--------------|-----------------|----------|
| **Pure JavaScript** (default) | ✅ Simple (`npx`) | ❌ No | Most users, quick setup |
| **Native Driver** (optional) | ⚠️ Complex (requires build tools) | ✅ Yes | Enterprise, security required |

### Quick Start (Default - No Wire Encryption)

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

### Advanced (With Wire Encryption Support)

⚠️ **CRITICAL**: `npx` does NOT work with the native driver. You MUST install globally.

⚠️ **IMPORTANT**: Wire encryption must be configured on the **Firebird server** (`firebird.conf`), not on the client.

**Server Configuration** (required first):
```conf
# In firebird.conf on the server
WireCrypt = Required  # or Enabled
```

**Client Installation** (MUST be global):
```bash
# 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
```

**Why not npx?** When `npx` runs a package from its temporary cache, it cannot access globally installed modules like `node-firebird-driver-native`. Both packages must be installed globally in the same location.

**📚 For detailed installation instructions, see:**
- [Native Driver Installation Guide](./docs/native-driver-installation.md) - **Step-by-step for Windows/Linux/macOS**
- [Wire Encryption Guide](./docs/wire-encryption-limitation.md)
- [Advanced Installation Guide](./docs/advanced-installation.md)

### Manual Installation

#### Stable Version
```bash
# Global installation
npm install -g mcp-firebird

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

**Stable features (2.12.3):**
- MCP 2026-07-28 alongside 2025 clients and legacy SSE, with shared server entry points.
- Structured tool contracts and opt-in SQL/HTTP security controls.
- Safe query/BLOB/transaction cleanup and configurable query deadlines.
- Full metadata descriptions, corrected statistics and registered tool counts.
- SQL grouping/window syntax recognition without bypassing explicit policies.
- Prepare-only optimizer plans and catalog-checked, single-table index advice that includes existing primary-key/composite indexes; no automatic DDL.
- Backward-compatible ISO/UTC date output by default; opt in with `FIREBIRD_DATE_FORMAT=wall-clock` and restart the MCP process only if your client needs it. See [date configuration](docs/blob-date-compatibility.md).
- See the [2.12.3 release notes](docs/releases/2.12.3.md), [2.12.2 date compatibility correction](docs/releases/2.12.2.md) and [2.12.1 accumulated fixes](docs/releases/2.12.1.md).

#### Alpha Version (Latest Features)
```bash
# Install alpha version with latest features
npm install -g mcp-firebird@alpha

# Or use specific alpha version
npm install -g mcp-firebird@2.13.0-alpha.1
```

**All improvements from alpha 2.13.0-alpha.1 are included in stable 2.12.3.** Use `mcp-firebird@latest` or pin `mcp-firebird@2.12.3`; no alpha installation is required for issue #45 diagnostics. The `alpha` tag remains at 2.13.0-alpha.1 for existing testers. No new flag, driver upgrade or security-policy relaxation is required, and the advisor never creates indexes. Keep your connection/security settings and restart the MCP after updating. Read the [diagnostics guide](docs/query-diagnostics.md), [stable release notes](docs/releases/2.12.3.md), [security guide](docs/security.md) and [date/BLOB compatibility notes](docs/blob-date-compatibility.md).



For VSCode and GitHub Copilot integration, see [VSCode Integration](./docs/vscode-integration.md).

## Basic Usage

### With Claude Desktop

1. Edit the Claude Desktop configuration:
   ```bash
   code $env:AppData\Claude\claude_desktop_config.json  # Windows
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json  # macOS
   ```

2. Add the MCP Firebird configuration:
   ```json
   {
     "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. Restart Claude Desktop

## Transport Configuration

MCP Firebird supports multiple transport protocols to accommodate different client needs and deployment scenarios.

### STDIO Transport (Default)

The STDIO transport is the standard method for Claude Desktop integration:

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

### SSE Transport (Server-Sent Events)

SSE transport allows the server to run as a web service, useful for web applications and remote access:

#### Basic SSE Configuration

```bash
# 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
```

#### Environment Variables for SSE

```bash
# 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 Client Connection

Once the SSE server is running, clients can connect to:
- **SSE Endpoint**: `http://localhost:3003/sse`
- **Messages Endpoint**: `http://localhost:3003/messages`
- **Health Check**: `http://localhost:3003/health`

### Streamable HTTP Transport (Modern)

The latest MCP protocol supporting bidirectional communication:

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

### Unified Transport (Recommended)

Supports both SSE and Streamable HTTP protocols simultaneously with automatic detection:

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

#### Unified Server Endpoints

- **SSE (Legacy)**: `http://localhost:3003/sse`
- **Streamable HTTP (Modern)**: `http://localhost:3003/mcp`
- **Protocol auto-detection**: `http://localhost:3003/mcp`
- **Health Check**: `http://localhost:3003/health`

### Configuration Examples

#### Development Setup (SSE)
```bash
npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database ./dev-database.fdb \
  --user SYSDBA \
  --password masterkey
```

#### Production Setup (Unified)
```bash
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
```

#### Docker with SSE
```bash
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
```

### Advanced SSE Configuration

#### Session Management

Configure session timeouts and limits:

```bash
# 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 Configuration

For browser applications, restrict access to one or more comma-separated origins. The default is `*` with browser credentials disabled, so existing STDIO and Bearer-token MCP clients remain compatible:

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

npx mcp-firebird --transport-type sse
```

**Stable 2.12.3 retains the 2.11/2.12 security improvements and historical date output by default, adding safe query diagnostics.** Install with `npm install -g mcp-firebird@latest`, or pin `mcp-firebird@2.12.3`. Explicit policies remain enforced; review the [migration guide](./docs/security.md#important-migration-notice) and [release notes](docs/releases/2.12.3.md). Date-format selection is a separate process environment setting, not a security-policy field.

Raw SQL writes are disabled by default. `2.11.0` preserves the historical `ALLOW_RAW_SQL=true` switch for writes, including DDL, without requiring new flags. Explicitly configured operation/table/row/masking/role restrictions and `sql.allowDDL=false` are never bypassed by that switch. See the [security guide](./docs/security.md) for opt-in controls and the structured `get-table-data` filter format.

Custom security files can be loaded with `--security-config /absolute/path/security-config.json` or the `FIREBIRD_SECURITY_CONFIG` environment variable. `SECURITY_CONFIG` and `SECURITY_CONFIG_PATH` are fallback aliases, in that order; the CLI option takes precedence over environment variables. Use a JSON object such as `{"security":{"allowedTables":["EMPLOYEES"],"allowedOperations":["SELECT"],"maxRows":100}}`. Trusted CommonJS files are also supported. Restart after changing the policy and check for `Loaded security configuration from ...`. Starting with `2.11.0-alpha.2`, invalid or missing selected files stop initialization instead of silently applying defaults. See the [security guide](./docs/security.md).

Starting with `2.11.0-alpha.1`, set `FIREBIRD_SECURITY_JSON` to that same JSON string to configure security without a file. SQL options are also supported. **In `2.11.0-alpha.3`, advanced restrictions are opt-in:** no implicit resource quotas, deadlines, catalog denial or new routine restrictions. Set only the controls you need; for example, `{"security":{"maxRows":100}}` activates just that row cap. Explicit policies are enforced, including options that older releases did not enforce. File paths take precedence. Only a trusted administrator/launcher may set the variable; HTTP/SSE clients cannot change it. Inline JSON is limited to 64 KiB (UTF-8), validated without executing code, and not logged by the loader. Invalid policies reject initialization. Unset the variable to disable that source and restart after changes. Review the [migration notice](./docs/security.md#important-migration-notice), [configuration examples](./docs/security.md#inline-json-configuration) and [implementation review](./docs/security-implementation-review.md).

#### SSL/TLS Support

For production deployments, use a reverse proxy like nginx:

```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;
    }
}
```

### Troubleshooting

#### Firebird Connection Issues

1. **Wire Encryption Incompatibility (Firebird 3.0+)** ⚠️ **CRITICAL**

   **Error**: `Incompatible wire encryption levels requested on client and server`

   **IMPORTANT**: The `node-firebird` library does NOT support Firebird 3.0+ wire encryption. The `--wire-crypt` parameter does NOT work.

   **ONLY Solution**: You MUST disable wire encryption on the Firebird server:

   For Firebird 3.0, add to `firebird.conf`:
   ```conf
   WireCrypt = Disabled
   AuthServer = Srp, Legacy_Auth
   ```

   For Firebird 4.0+, add to `firebird.conf`:
   ```conf
   WireCrypt = Disabled
   AuthServer = Srp256, Srp, Legacy_Auth
   ```

   For Firebird 5.0 Docker:
   ```yaml
   environment:
     FIREBIRD_CONF_WireCrypt: Disabled
     FIREBIRD_CONF_AuthServer: Srp256, Srp
   ```

   **If you cannot change server configuration**, see [Wire Encryption Limitation](./docs/wire-encryption-limitation.md) for alternatives.

2. **Database Path Issues on Linux/Unix**

   **Problem**: Remote connection strings or Unix paths not working

   **Solution**: This is fixed in v2.4.0-alpha.1+. The following paths now work correctly:
   - Remote: `server:/path/to/database.fdb`
   - Unix absolute: `/var/lib/firebird/database.fdb`
   - IP-based: `192.168.1.100:/data/db.fdb`

3. **I/O Error with Mixed-Case Paths on Windows**

   **Error**: `I/O error during CreateFile (open) operation`

   **Problem**: Database path with mixed case (e.g., `C:\MyData\database.fdb`) causes errors

   **Workarounds**:
   - Use all-uppercase paths: `C:\MYDATA\DATABASE.FDB`
   - Use forward slashes: `C:/MyData/database.fdb`
   - See [Wire Encryption Fix Documentation](./docs/wire-encryption-fix.md#error-io-error-in-windows-with-mixed-case-paths) for more details

#### SSE Connection Issues

1. **Connection Refused**
   ```bash
   # Check if server is running
   curl http://localhost:3003/health

   # Check port availability
   netstat -an | grep 3003
   ```

2. **Session Timeout**
   ```bash
   # Increase session timeout
   export SSE_SESSION_TIMEOUT_MS=3600000  # 1 hour
   ```

3. **CORS Errors**
   ```bash
   # Allow all origins (development only)
   export CORS_ORIGIN="*"
   ```

4. **Memory Issues**
   ```bash
   # Reduce max sessions
   export MAX_SESSIONS=100

   # Enable more frequent cleanup
   export SESSION_CLEANUP_INTERVAL_MS=30000
   ```

5. **JSON Parsing Issues (Fixed in v2.3.0-alpha.1+)**
   ```bash
   # 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
   ```

   **Note**: Versions prior to 2.3.0-alpha.1 had a bug where POST requests to `/messages`
   endpoint failed to parse JSON body correctly. This has been fixed with improved
   middleware handling for both `application/json` and `text/plain` content types.

#### Monitoring and Logging

```bash
# 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'
```




## Documentation

For more detailed information, check the following documents:

### Getting Started
- [Complete Installation](./docs/installation.md)
- [Configuration Options](./docs/configuration.md)
- [Available Tools](./docs/tools.md)
- [Database Metadata Tools](./docs/metadata-tools.md) - Inspect triggers, procedures, functions, and packages
- [Resources, Tools, and Prompts Reference](./docs/resources-tools-prompts.md) - Complete guide to all MCP capabilities

### Transport Protocols
- [Transport Configuration](./docs/transport-types.md)

### Integration Guides
- [VSCode Integration](./docs/vscode-integration.md)
- [Docker Configuration](./docs/docker.md)
- [Usage from Different Languages](./docs/clients.md)

### Advanced Topics
- [Security](./docs/security.md)
- [Troubleshooting](./docs/troubleshooting.md)
- [Wire Encryption Fix](./docs/wire-encryption-limitation.md) - Firebird 3.0+ compatibility and Linux path fix

### Examples and Use Cases
- [Use Cases and Examples](./docs/use-cases.md)


## Support the Project

### Donations

If you find MCP Firebird useful for your work or projects, please consider supporting its development through a donation. Your contributions help maintain and improve this tool.

- **GitHub Sponsors**: [Sponsor @PuroDelphi](https://github.com/sponsors/PuroDelphi)
- **PayPal**: [Donate via PayPal](https://www.paypal.com/donate/?hosted_button_id=KBAUBYYDNHQNQ)

![image](https://github.com/user-attachments/assets/d04cf0eb-32a8-48a7-9324-c02af5269370)


### Hire Our AI Agents

Another great way to support this project is by hiring our AI agents through [Asistentes Autónomos](https://asistentesautonomos.com). We offer specialized AI assistants for various business needs, helping you automate tasks and improve productivity.

### Priority Support

⭐ **Donors, sponsors, and clients receive priority support and assistance** with issues, feature requests, and implementation guidance. While we strive to help all users, those who support the project financially will receive faster response times and dedicated assistance.

Your support is greatly appreciated and helps ensure the continued development of MCP Firebird!

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.