Firebird SQL MCP server for AI agents

MCP Firebird is a server that implements Anthropic's Model Context Protocol (MCP) for Firebird SQL databases. It enables Large Language Models like Claude to securely access, analyze, and manipulate data in Firebird databases through a controlled interface, allowing for SQL queries, schema analysis, and database management operations.

Installation

Standard Installation

# Global installation (stable)
npm install -g mcp-firebird

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

Alpha Version Installation

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

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

The alpha version includes these features:

Streamable HTTP transport support (MCP 2025-03-26)
Unified server with automatic protocol detection
Enhanced session management and monitoring
Modern MCP SDK integration (v1.13.2)
Improved error handling and logging

Basic Usage

Using with Claude Desktop

Edit the Claude Desktop configuration:

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

Add the MCP Firebird configuration:

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

Restart Claude Desktop

Transport Configuration

STDIO Transport (Default)

Best for Claude Desktop integration:

{
  "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)

For web applications and remote access:

# 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

Using environment variables:

# 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 endpoints:

SSE Endpoint: http://localhost:3003/sse
Messages Endpoint: http://localhost:3003/messages
Health Check: http://localhost:3003/health

Streamable HTTP Transport (Modern)

Latest MCP protocol with bidirectional communication:

# 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 with automatic detection:

# Start unified server
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
Auto-Detection: http://localhost:3003/mcp-auto
Health Check: http://localhost:3003/health

Configuration Examples

Development Setup (SSE)

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

Production Setup (Unified)

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

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 Configuration

Session Management

Configure session timeouts and limits:

# 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 web applications:

# Allow specific origins
export CORS_ORIGIN="https://myapp.com,https://localhost:3000"
export CORS_METHODS="GET,POST,OPTIONS"
export CORS_HEADERS="Content-Type,mcp-session-id"

npx mcp-firebird --transport-type sse

Troubleshooting

Common Issues

Connection Refused

# Check if server is running
curl http://localhost:3003/health

# Check port availability
netstat -an | grep 3003

Session Timeout

# Increase session timeout
export SSE_SESSION_TIMEOUT_MS=3600000  # 1 hour

CORS Errors

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

Memory Issues

# Reduce max sessions
export MAX_SESSIONS=100

# Enable more frequent cleanup
export SESSION_CLEANUP_INTERVAL_MS=30000

Monitoring and Logging

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

Quick Install via Smithery

For automatic installation with Claude Desktop:

npx -y @smithery/cli install @PuroDelphi/mcpFirebird --client claude

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "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 for the changes to take effect