🚀 Bun Database MCP Server

A high-performance Model Context Protocol (MCP) server built with Bun and TypeScript, providing secure database operations for MySQL databases. This server enables AI assistants to safely interact with MySQL databases through a standardized protocol.

📹 Video Tutorials

Watch these comprehensive tutorials to understand MCP development:

✨ Features

• 🔌 Database Connection Management - Connect, disconnect, and check connection status

• 🔍 Safe Query Execution - Execute SELECT queries with parameterized statements

• 📝 CRUD Operations - Create, Read, Update, and Delete records securely

• 📊 Schema Inspection - Read database schema and table structures

• 🤖 MCP Prompts - Pre-built prompts for common database operations

• 📚 MCP Resources - Access database documentation and schema information

• 🛡️ SQL Injection Prevention - Built-in validation and sanitization

• ⚡ Built with Bun - Lightning-fast runtime and package management

• 🔒 Environment-based Configuration - Secure credential management

📋 Prerequisites

• Bun v1.0 or higher

• MySQL 5.7+ or MySQL 8.0+

• Node.js 18+ (for compatibility)

🛠️ Installation

1. Clone the repository:

2. Install dependencies:

3. Configure environment variables:

Edit .env with your database credentials:

4. Initialize the database with sample data:

The repository includes an simple_import_employees.sql file with sample employee data. Import it using one of these methods.

Option 1: Using mysql command-line client:

Option 2: From within MySQL client:

Then run:

Option 3: Using mysqldump (for backup/restore):

🚀 Usage

Transport Options

The MCP server supports three different transport protocols:

1. STDIO Transport (Default)

Standard input/output communication for MCP clients like Claude Desktop:

2. SSE Transport (Server-Sent Events)

HTTP-based transport using Server-Sent Events for real-time streaming:

• Endpoints:

  • GET http://localhost:3000/mcp - Establish SSE stream

  • POST http://localhost:3000/messages - Send JSON-RPC requests

• Session Management: Via sessionId query parameter

3. HTTP Transport (StreamableHTTP with OAuth)

Modern HTTP transport with OAuth authentication supporting both JSON and SSE responses:

• MCP Endpoint: GET/POST http://localhost:3000/mcp

• Auth Server: http://localhost:3001 (OAuth provider with demo flows)

• Session Management: Via Mcp-Session-Id header

• Authentication: Bearer token required in Authorization header

• Response Formats:

  • JSON: Accept: application/json, text/event-stream

  • SSE: Accept: text/event-stream, application/json

Authentication Flow:

1. OAuth server runs on port 3001 with demo authentication flows

2. Supports both in-memory demo provider and Google OAuth

3. MCP server validates Bearer tokens for protected resources

4. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET environment variables for Google OAuth

Starting the Server

Run with default STDIO transport:

Run with specific transport:

For development with auto-reload:

Available Tools

The server provides six powerful tools for database operations:

1. connection - Manage Database Connection

2. query - Execute SELECT Queries

3. create - Insert Records

4. update - Update Records

5. delete - Delete Records

6. readSchema - Inspect Database Schema

Available Prompts

The server provides pre-built prompts for common database operations:

1. query-employees - Natural Language Queries

Query the employees table using natural language instructions.

• Arguments: instructions - e.g., "count female employees", "show 10 recent hires"

2. insert-employee - Add New Employee

Insert a new employee with all related information (department, title, salary).

• Arguments: employee_info - Employee details in natural language

3. delete-employee - Remove Employee

Delete an employee and all related records from the database.

• Arguments: employee_identifier - Employee number or name

4. manage-departments - Department Operations

Insert a new department or delete an existing department.

• Arguments: instructions - e.g., "add Marketing department", "delete department d005"

Available Resources

The server exposes the following MCP resources:

bun-db-mcp://general-database - Database Schema Documentation

• Type: text/markdown

• Description: Complete documentation of the employee database schema including:

  • Table structures and columns

  • Entity relationships

  • Key design patterns

  • Common query patterns

  • Mermaid ER diagram

🧪 Testing

Run the test suite:

Run specific test files:

Watch mode for development:

🔧 Configuration

MCP Client Configuration

STDIO Transport (Claude Desktop)

To use with Claude Desktop or other MCP clients, add to your configuration:

HTTP/SSE Transport (Web Clients)

For HTTP-based transports, use curl or web clients:

SSE Transport Example:

HTTP Transport with OAuth Example:

Environment Variables

🏗️ Project Structure

🔒 Security Features

• OAuth Authentication - Bearer token authentication for HTTP transport

• Protected Resources - Access control for sensitive database operations

• Parameterized Queries - All queries use prepared statements to prevent SQL injection

• Input Validation - Table and column names are validated against strict patterns

• Identifier Escaping - Database identifiers are properly escaped

• SELECT-only Queries - Query tool restricted to SELECT statements only

• Environment Variables - Sensitive credentials stored in environment files

• CORS Protection - Configurable cross-origin resource sharing policies

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Bun - The fast all-in-one JavaScript runtime

• Uses MCP SDK for protocol implementation

• Database connectivity via mysql2

📊 Performance

Thanks to Bun's optimized runtime:

• 🚀 Fast Startup - Server starts in milliseconds

• ⚡ Low Memory - Efficient memory usage

• 🔥 High Throughput - Handle multiple database operations efficiently

🐛 Troubleshooting

Common Issues

1. Connection Refused

   • Verify MySQL is running

   • Check host and port in .env

   • Ensure user has proper permissions

2. Authentication Failed

   • Verify credentials in .env

   • Check MySQL user permissions

   • Ensure database exists

3. Module Not Found

   • Run bun install to install dependencies

   • Verify Bun version with bun --version

📞 Support

For issues and questions:

• Open an issue on GitHub Issues

• Check existing issues for solutions

• Provide detailed error messages and steps to reproduce

Built with ❤️ using Bun and TypeScript