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) for Firebird SQL databases. It allows Large Language Models (LLMs) like Claude to access, analyze, and manipulate data in Firebird databases securely and in a controlled manner.

Key Features

SQL Queries: Execute SQL queries on Firebird databases
Schema Analysis: Get detailed information about tables, columns, and relationships
Database Management: Perform backup, restore, and validation operations
Performance Analysis: Analyze query performance and suggest optimizations
Multiple Transports: Supports STDIO, SSE (Server-Sent Events), and Streamable HTTP transports
Modern Protocol Support: Full support for MCP Streamable HTTP (2025-03-26) and legacy SSE
Unified Server: Automatic protocol detection and backwards compatibility
Claude Integration: Works seamlessly with Claude Desktop and other MCP clients
VSCode Integration: Works with GitHub Copilot in Visual Studio Code
Session Management: Robust session handling with automatic cleanup and configurable timeouts
Security: Includes SQL query validation and security configuration options

Manual Installation

Stable Version

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

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

# Or use specific stable version
npm install -g mcp-firebird@2.2.3

Stable Features (v2.2.3):

🐛 FIXED: SSE JSON parsing bug - resolves "Invalid message: [object Object]" errors
✨ 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
🧪 Comprehensive test suite with 9+ tests for SSE functionality

Alpha Version (Latest Features)

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

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

Alpha Features (v2.3.0-alpha.1):

🐛 FIXED: SSE JSON parsing bug - resolves "Invalid message: [object Object]" errors
✨ 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
🧪 Comprehensive test suite with 9+ tests for SSE functionality
📚 Enhanced documentation with troubleshooting guides

For backup/restore operations, you'll need to install the Firebird client tools. See Complete Installation for more details.

For VSCode and GitHub Copilot integration, see VSCode Integration.

Basic Usage

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

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:

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

# 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

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

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

# 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
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 SSE 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, configure CORS settings:

# 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

SSL/TLS Support

For production deployments, use a reverse proxy like 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 SSE

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
JSON Parsing Issues (Fixed in 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
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

# 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 Installation via Smithery

To install MCP Firebird for Claude Desktop automatically via Smithery:

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

Documentation

For more detailed information, check the following documents:

Getting Started

Transport Protocols

Integration Guides

Advanced Topics

Session Management
Security
Performance Tuning
Troubleshooting
SSE JSON Parsing Fix - Details about the v2.3.0-alpha.1 bug fix

Examples and Use Cases

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
PayPal: Donate via PayPal

Hire Our AI Agents

Another great way to support this project is by hiring our AI agents through Asistentes Autónomos. 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 file for details.

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all tools

A server implementing Anthropic's Model Context Protocol (MCP) for Firebird SQL databases, enabling Claude and other LLMs to securely access, analyze, and manipulate data in Firebird databases through natural language.

Related Resources

Reddit Discussion about this server

Related MCP Servers

db-mcp-tool
wirdes
A
security
A
license
A
quality
A powerful Model Context Protocol (MCP) tool for exploring and managing different types of databases including PostgreSQL, MySQL, and Firestore.
Last updated -
9
5
MIT License
Quick-start Auto MCP
teddynote-lab
-
security
A
license
-
quality
A tool that helps easily register Anthropic's Model Context Protocol (MCP) in Claude Desktop and Cursor, providing RAG functionality, Dify integration, and web search capabilities.
Last updated -
184
MIT License
Firestore Advanced MCP
diez7lm
-
security
A
license
-
quality
A Model Context Protocol server that enables large language models like Claude to perform comprehensive interactions with Firebase Firestore databases, supporting full CRUD operations, complex queries, and advanced features like transactions and TTL management.
Last updated -
5
4
MIT License
Natural Language MySQL Query System
floatDreamWithSong
-
security
F
license
-
quality
A Model Context Protocol (MCP) server that converts natural language queries into SQL statements, allowing users to query MySQL databases using conversational language instead of writing SQL code.
Last updated -
3

View all related MCP servers