MCP Database Console

A revolutionary web application that bridges the gap between natural language and database queries

🚀 Quick Start • 📖 Documentation • 🤝 Contributing

---

🚀 What is MCP Database Console?

MCP Database Console is a cutting-edge web application that transforms natural language into powerful database queries. Built with Next.js and powered by the MCP-DB Connector, it democratizes database access by allowing users to interact with databases using plain English instead of complex SQL syntax.

🎯 The Problem We Solve

• SQL Complexity: Writing SQL queries requires technical expertise and knowledge of database schemas
• Accessibility: Non-technical users struggle to extract insights from databases
• Time Consumption: Developers spend significant time writing and debugging SQL queries
• Learning Curve: New team members need time to understand database structures

💡 Our Solution

Transform natural language into powerful database queries through an intuitive web interface that:

• Understands Context: Interprets user intent from conversational prompts
• Supports Multiple Databases: Works with SQLAlchemy, Snowflake, and SQLite databases (backend implementation required)
• Provides Real-time Results: Shows query results instantly in formatted tables
• Handles Errors Gracefully: Offers helpful error messages and suggestions

🌟 Key Benefits

• Democratize Data Access: Enable non-technical users to query databases
• Increase Productivity: Reduce time spent on query writing and debugging
• Improve Accuracy: Minimize SQL syntax errors through natural language processing
• Enhance Collaboration: Allow team members to share insights without SQL knowledge

---

🎉 Hacktoberfest 2025

This repository is participating in Hacktoberfest 2025! We welcome contributions from developers of all skill levels. After 15 approved pull requests, you'll be recognized as a project collaborator!

🏆 Mid-Hacktoberfest Update

We're halfway through Hacktoberfest 2025 and the response has been incredible! Here's our progress:

🎯 Top Contributors (as of mid-October 2025):

🥇 @Andrew Qu - 17 commits - Contributing valuable improvements and bug fixes

🥈 @Sheikh Mohammad Nazmul H. - 17 commits - Implementing authentication features and code refactoring

🥉 @Malte Ubl - 13 commits - Providing technical expertise and code improvements

📊 Community Impact:

• 30+ active contributors from around the world
• 100+ commits since October 1st
• Major features added: Authentication system, keyboard shortcuts, structured logging, deployment automation
• Multiple languages and frameworks represented in our contributor base

🚀 Recent Achievements:

• ✅ JWT-based Role-Based Access Control (RBAC) system
• ✅ Keyboard shortcuts for power users
• ✅ Structured JSON logging with correlation IDs
• ✅ Automated deployment workflows
• ✅ Enhanced error handling with actionable suggestions
• ✅ User management API with authentication

🎯 Next Milestone: We're looking forward to recognizing our first project collaborators after they reach 15 approved PRs!

🎬 Visual Tour

Here are some screenshots/GIF showcasing the features of mcp-for-database:

Homepage

Central dashboard with high-level metrics and quick actions.

Database Console

Query your database using plain English and view results instantly.

Live Demo (GIF)

An animated demonstration of exploring features of mcp-for-database.

Database Console in Action (GIF)

Watch how to use natural language to query your database:

1. Connect to your preferred database (SQLite/Snowflake)

2. Type your query in plain English

3. See the results instantly in a formatted table

Quick Start for Contributors

---

Local development (mock MCP)

If you don't have a running MCP-DB Connector locally, the repository includes a small mock server to exercise the frontend during development.

• Start the mock MCP server (listens on port 8000 by default):

npm run mock:mcp

• Start the Next.js dev server in a separate terminal:

npm run dev

• Open the app and try the Test Connection button:

  • Visit http://localhost:3000/db-console
  • Choose a target (e.g. snowflake or sqlite) and click Test Connection

• You can also call the mock endpoints directly for quick checks:

# POST to mock test-connection
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/test-connection -Body (@{ target = 'snowflake' } | ConvertTo-Json) -ContentType 'application/json'

# POST a mock query
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/query -Body (@{ sql = 'select 1' } | ConvertTo-Json) -ContentType 'application/json'

Notes:

• The mock server logs incoming requests to the terminal to help with debugging.
• If port 8000 is already in use, set MOCK_MCP_PORT before running the mock, and update MCP_SERVER_URL in .env.local if necessary.

1. Fork this repository
2. Star the repository (optional but appreciated!)
3. Check our Contributing Guidelines
4. Look for issues labeled hacktoberfest or good first issue
5. Create a pull request with your contribution
6. Get recognized as a collaborator after 15 approved PRs!

---

👥 Use Cases

🏢 Business Analysts

• Quick Data Insights: Get answers to business questions without waiting for developers
• Ad-hoc Reporting: Create reports on-demand using natural language
• Data Exploration: Discover patterns and trends in company data

👨‍💼 Product Managers

• User Analytics: Understand user behavior and product metrics
• Feature Analysis: Analyze feature adoption and performance
• Competitive Intelligence: Gather insights from market data

🎓 Data Scientists

• Rapid Prototyping: Quickly test hypotheses with natural language queries
• Data Validation: Verify data quality and consistency
• Exploratory Analysis: Initial data exploration before deep analysis

🏭 Operations Teams

• System Monitoring: Query system logs and performance metrics
• Incident Analysis: Investigate issues using natural language
• Capacity Planning: Analyze resource usage patterns

🎓 Students & Researchers

• Learning SQL: Understand database concepts through natural language
• Research Data: Query academic databases and research datasets
• Project Analysis: Analyze project data for academic research

---

🎯 MVP (Minimum Viable Product)

Core Features ✅

• Natural Language Query Interface: Basic English-to-SQL conversion
• Database Support: SQLAlchemy and Snowflake connectors
• Results Display: Formatted table output with query execution time
• Error Handling: User-friendly error messages and validation
• Responsive UI: Clean, modern interface built with TailwindCSS

Current Status: MVP Complete 🚀

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or pnpm
• MCP-DB Connector server running on http://localhost:8000

Installation

1. Clone the repository

   git clone https://github.com/Limeload/mcp-for-database.git
   cd mcp-for-database

2. Install dependencies

   npm install
   # or
   pnpm install

3. Start the development server

   npm run dev

4. Open your browser Navigate to http://localhost:3000

SQLite Local Development Setup

For local development with SQLite, follow these additional steps:

1. Set up environment variables for SQLite:

   # Create .env.local file
   DATABASE_TYPE=sqlite
   DATABASE_URL=sqlite:///local_dev.db

2. Initialize the SQLite database (requires Python and SQLAlchemy):

   # Install Python dependencies (if not already installed)
   pip install sqlalchemy
   
   # Initialize database
   python scripts/init_sqlite.py
   
   # Optional: Add sample data
   python scripts/seed_data.py

3. Configure your MCP server to use SQLite backend

   ⚠️ Important: The MCP-DB Connector server must be updated to support SQLite queries. The frontend now accepts SQLite as a target, but the backend server needs corresponding SQLite support.

4. Start both servers:

   # Terminal 1: Start MCP server (with SQLite support)
   # Your MCP server command here
   
   # Terminal 2: Start Next.js development server
   npm run dev

SQLite Benefits for Development:

• No external database server required
• File-based storage (local_dev.db)
• Easy to reset and recreate
• Perfect for testing and development

SQLite Limitations:

• Single-writer concurrency (not suitable for high-traffic production)
• No built-in user authentication or permissions
• Limited data types compared to PostgreSQL/MySQL
• File-based (backup and replication require manual processes)

Usage

Database Console

Navigate to /db-console to access the database query interface:

1. Enter a Prompt: Describe what you want to query in natural language

   • Example: "Show me all users who registered in the last 30 days"
   • Example: "Find the top 10 products by sales"

2. Select Database Target: Choose between:

   • SQLAlchemy: For SQLAlchemy-based applications
   • Snowflake: For Snowflake data warehouse
   • SQLite: For local development with SQLite database

3. Execute Query: Click "Execute Query" to run your prompt

4. View Results: Results are displayed in a formatted table with:

   • Generated SQL query (if available)
   • Query execution time
   • Data results in tabular format

---

📖 Documentation

• Contributing Guidelines - How to contribute to the project
• Code of Conduct - Community standards and behavior
• Security Policy - Security guidelines and vulnerability reporting
• Contributors - List of project collaborators
• Roadmap - Detailed development roadmap and future plans
• API Documentation - Complete API reference
• Development Guide - Development setup and guidelines
• Deployment Guide - Deployment options and instructions

---

🔧 API Reference

POST /api/db/[query]

Execute a database query using natural language.

Request Body:

{
  "prompt": "string",
  "target": "sqlalchemy" | "snowflake" | "sqlite"
}

Response:

{
  "status": "success",
  "data": [...],
  "error": null,
  "metadata": {
    "query": "SELECT ...",
    "executionTime": 150
  }
}

Error Response:

{
  "status": "error",
  "data": null,
  "error": {
    "message": "Error message",
    "code": "VALIDATION_ERROR"
  }
}

---

⚙️ Configuration

MCP Server

The application expects the MCP-DB Connector server to be running on http://localhost:8000. Update the URL in /app/api/db/[query]/route.ts if your MCP server runs on a different port.

Environment Variables

Create a .env.local file in the root directory:

# MCP Server Configuration
MCP_SERVER_URL=http://localhost:8000

# Database Configuration (if needed)
DATABASE_URL=your_database_url

TailwindCSS

The project uses TailwindCSS for styling. Configuration files:

• tailwind.config.js - TailwindCSS configuration
• postcss.config.js - PostCSS configuration
• app/globals.css - Global styles

---

🧪 Development

Available Scripts

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

# Testing
npm test             # Run tests (when implemented)

Building for Production

npm run build
npm start

TypeScript

The project is fully typed with TypeScript. All API responses and component props are properly typed.

---

🛡️ Error Handling

The application includes comprehensive error handling:

• Network Errors: When the MCP server is unreachable
• Validation Errors: For missing or invalid request parameters
• Server Errors: When the MCP server returns an error
• Client Errors: For malformed requests

All errors are displayed to the user with clear, actionable messages.

---

🤝 Contributing

We welcome contributions from the community! This project is participating in Hacktoberfest 2025.

For Contributors

• 📖 Read our Contributing Guidelines
• 📋 Check our Code of Conduct
• 🏆 See our Contributors page
• 🎯 Look for issues labeled hacktoberfest or good first issue

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Recognition

After 15 approved pull requests, you'll be:

• Added to our Contributors list
• Recognized as a project collaborator
• Eligible for Hacktoberfest completion

🏆 Current Leaderboard

Top Contributors (Mid-Hacktoberfest 2025):

1. @Andrew Qu - 17 commits 🥇
2. @Sheikh Mohammad Nazmul H. - 17 commits 🥈
3. @Malte Ubl - 13 commits 🥉

Leaderboard updates daily during Hacktoberfest

---

📄 License

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

---

🙏 Acknowledgments

• Next.js team for the amazing framework
• TailwindCSS for the utility-first CSS framework
• MCP-DB Connector for the database integration
• Hacktoberfest community for inspiring open-source contributions

🌟 Special Thanks to Our Top Contributors

• @Andrew Qu - For valuable improvements and bug fixes
• @Sheikh Mohammad Nazmul H. - For implementing authentication features and code refactoring
• @Malte Ubl - For providing technical expertise and code improvements
• All 30+ contributors who have made this project what it is today!

Thank you for making MCP Database Console better with every contribution! 🚀

---

Made with ❤️ for the open-source community

⭐ Star this repo • 🐛 Report Bug • ✨ Request Feature