{"id":31936925,"url":"https://github.com/pulkit0111/db_rag_mcp","last_synced_at":"2026-04-12T00:44:45.572Z","repository":{"id":315734160,"uuid":"1060627330","full_name":"Pulkit0111/db_rag_mcp","owner":"Pulkit0111","description":"Chat with your database using plain English!  This is a Model Context Protocol (MCP) server that transforms natural language into SQL queries using AI. Instead of writing complex SQL, just ask questions like \"Show me all users from New York\" and get instant results.","archived":false,"fork":false,"pushed_at":"2025-09-29T14:21:14.000Z","size":223,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T16:25:20.021Z","etag":null,"topics":["fastmcp","mcp","mcp-server","openai","postgresql","sql"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pulkit0111.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-20T09:11:36.000Z","updated_at":"2025-09-29T14:21:15.000Z","dependencies_parsed_at":"2025-09-20T12:24:49.959Z","dependency_job_id":null,"html_url":"https://github.com/Pulkit0111/db_rag_mcp","commit_stats":null,"previous_names":["pulkit0111/db_rag_mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Pulkit0111/db_rag_mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pulkit0111%2Fdb_rag_mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pulkit0111%2Fdb_rag_mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pulkit0111%2Fdb_rag_mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pulkit0111%2Fdb_rag_mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pulkit0111","download_url":"https://codeload.github.com/Pulkit0111/db_rag_mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pulkit0111%2Fdb_rag_mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018199,"owners_count":26086307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastmcp","mcp","mcp-server","openai","postgresql","sql"],"created_at":"2025-10-14T07:54:06.381Z","updated_at":"2025-10-14T07:54:07.536Z","avatar_url":"https://github.com/Pulkit0111.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Natural Language SQL MCP Server v2.0.0\n\n**The most comprehensive AI-powered database interface - Chat with your database using plain English!**\n\nTransform natural language into SQL queries, visualize data, export results, and manage multiple databases with enterprise-grade features. This advanced MCP server provides a complete database interaction ecosystem with AI-powered intelligence.\n\n## ✨ What Makes This Special?\n\nThis isn't just another SQL translator. It's a **complete database interaction platform** that combines:\n\n- 🧠 **AI-Powered Query Intelligence** - Smart suggestions, optimizations, and result explanations\n- 🎨 **Interactive Data Visualization** - Beautiful charts and dashboards with Plotly\n- 🔐 **Enterprise Security** - Full RBAC with user authentication and session management\n- 🗄️ **Multi-Database Support** - PostgreSQL, MySQL, and SQLite\n- 📊 **Advanced Analytics** - Query optimization, performance insights, and trend analysis\n- 💾 **Multiple Export Formats** - CSV, JSON, Excel with metadata\n- 🧭 **Session Management** - Query history, context awareness, and smart suggestions\n- ⚡ **High Performance** - Redis caching, connection pooling, and optimized queries\n\nPerfect for developers, data analysts, business intelligence teams, and enterprises who want to democratize database access!\n\n## 🏗️ Architecture Overview\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   MCP Client    │    │   FastMCP Server │    │   Databases     │\n│  (Cursor IDE)   │◄──►│     (38 Tools)   │◄──►│ PostgreSQL/     │\n│                 │    │                  │    │ MySQL/SQLite    │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                │\n                       ┌──────────────────┐\n                       │  AI Intelligence │\n                       │   OpenAI GPT-4   │\n                       │  Query Analysis  │\n                       │  Optimizations   │\n                       └──────────────────┘\n```\n\n## 🛠️ Complete Feature Set (38 Tools)\n\n### 🔌 **Core Database Operations**\n- **`connect_database`** - Multi-database connection (PostgreSQL/MySQL/SQLite)\n- **`disconnect_database`** - Safe connection management\n- **`get_connection_status`** - Real-time connection monitoring\n\n### 📊 **Schema Intelligence**\n- **`list_tables`** - Smart table discovery with caching\n- **`describe_table`** - Comprehensive schema analysis\n- **`get_database_summary`** - AI-powered database overview\n\n### 💬 **Natural Language Queries**\n- **`query_data`** - Advanced NL to SQL with caching\n- **`add_data`** - Intelligent data insertion\n- **`update_data`** - Smart data modification\n- **`delete_data`** - Safe data removal with validation\n\n### 🧠 **AI-Powered Query Intelligence**\n- **`explain_results`** - Natural language result explanations\n- **`suggest_related_queries`** - Context-aware query suggestions  \n- **`optimize_query`** - Performance analysis and recommendations\n- **`improve_query_language`** - Query phrasing improvements\n- **`analyze_query_intent`** - Deep intent analysis and insights\n\n### 📈 **Advanced Query Features**\n- **`explain_query`** - Query execution planning and analysis\n- **`query_with_suggestions`** - Queries with optimization hints\n- **`aggregate_data`** - Specialized aggregation operations\n\n### 📚 **Session \u0026 History Management**\n- **`get_query_history`** - Rich query history with analytics\n- **`repeat_query`** - One-click query re-execution\n\n### 🔐 **Enterprise Authentication \u0026 Security**\n- **`authenticate_user`** - Secure user authentication\n- **`logout_user`** - Session management\n- **`get_current_user`** - User profile and permissions\n- **`create_user`** - User management (Admin)\n- **`list_users`** - User administration (Admin)\n- **`update_user_role`** - Role management (Admin)  \n- **`deactivate_user`** - Account management (Admin)\n- **`check_permission`** - Permission validation\n\n### 📊 **Data Visualization**\n- **`create_visualization`** - Interactive Plotly charts\n- **`recommend_visualizations`** - AI-suggested chart types\n- **`create_dashboard`** - Multi-chart dashboards\n- **`export_visualization`** - Chart export capabilities\n\n### 💾 **Data Export \u0026 Reporting**\n- **`export_csv`** - Enhanced CSV export with metadata\n- **`export_json`** - Structured JSON export  \n- **`export_excel`** - Multi-sheet Excel workbooks\n- **`export_multiple_formats`** - Bulk export operations\n\n### 🔧 **System \u0026 Utilities**\n- **`hello`** - Server connectivity test\n- **`server_info`** - Comprehensive system status\n\n## 🚀 Installation \u0026 Setup\n\n### Prerequisites\n- **Python 3.9+** ([Download](https://www.python.org/downloads/))\n- **Database** (PostgreSQL/MySQL/SQLite)\n- **OpenAI API Key** ([Get one](https://platform.openai.com/api-keys))\n- **Redis** (optional, for caching) ([Install guide](https://redis.io/docs/getting-started/installation/))\n\n### Step 1: Clone \u0026 Install\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd db-rag\n\n# Install all dependencies\npip install -r requirements.txt\n\n# Install additional dependencies\npip install pydantic-settings redis\n```\n\n### Step 2: Environment Configuration\nCreate a comprehensive `.env` file:\n\n```bash\n# ====================================\n# DATABASE CONFIGURATION\n# ====================================\nDB_HOST=localhost\nDB_PORT=5432\nDB_USERNAME=postgres\nDB_PASSWORD=your_password\nDB_DATABASE=your_database\nDB_TYPE=postgresql\n\n# ====================================\n# AI CONFIGURATION  \n# ====================================\nLLM_API_KEY=sk-your-openai-key-here\nLLM_MODEL=gpt-4o-mini\nLLM_MAX_TOKENS=1000\nLLM_TEMPERATURE=0.1\n\n# ====================================\n# SERVER CONFIGURATION\n# ====================================\nMCP_SERVER_NAME=Natural Language SQL Server\nMCP_HOST=127.0.0.1\nMCP_PORT=8000\nMCP_TRANSPORT=http\n\n# ====================================\n# FEATURE FLAGS\n# ====================================\nENABLE_AUTHENTICATION=false\nENABLE_QUERY_CACHING=true\nENABLE_QUERY_HISTORY=true\nENABLE_SMART_SUGGESTIONS=true\nENABLE_VISUALIZATION=true\n\n# ====================================\n# PERFORMANCE \u0026 CACHING\n# ====================================\nCACHE_REDIS_URL=redis://localhost:6379\nCACHE_TTL=300\nQUERY_TIMEOUT=30\nMAX_RESULT_ROWS=1000\n\n# ====================================\n# ENVIRONMENT\n# ====================================\nENVIRONMENT=development\nDEBUG=false\n```\n\n### Step 3: Launch Server\n```bash\npython src/server.py\n```\n\nExpected startup output:\n```\n============================================================\n🚀 NATURAL LANGUAGE SQL MCP SERVER v2.0.0\n============================================================\n✅ Configuration loaded successfully\n   Database: postgresql at localhost:5432\n   LLM Model: gpt-4o-mini\n\n🔧 Feature Status:\n   Authentication: ❌ Disabled\n   Query Caching: ✅ Enabled\n   Query History: ✅ Enabled\n   AI Suggestions: ✅ Enabled\n   Visualizations: ✅ Enabled\n\n🔨 Tools Registered: 38 tools available\n\n📊 Supported Databases: PostgreSQL, MySQL, SQLite\n🤖 AI Features: OpenAI GPT-4o-mini (default)\n📈 Visualization: Plotly-based interactive charts\n💾 Export Formats: CSV, JSON, Excel\n============================================================\n\n📡 Starting Natural Language SQL Server with STDIO transport\n   Ready for MCP client connections\n============================================================\n```\n\n## 🔧 Integration with Cursor IDE\n\n### MCP Server Configuration\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"natural-language-sql\": {\n      \"name\": \"Natural Language SQL Server v2.0\",\n      \"command\": \"python\",\n      \"args\": [\"src/server.py\"],\n      \"cwd\": \"/path/to/db-rag\",\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/db-rag\"\n      },\n      \"description\": \"Advanced AI-powered database interface with 38 tools\",\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### Quick Start Conversation\n```\nYou: Connect to my database and show me what tables I have\n\nAI: I'll connect to your database and show you the available tables.\n[Uses connect_database and list_tables tools]\nConnected! You have 15 tables: users, orders, products, categories...\n\nYou: Show me sales trends for the last 3 months with a chart\n\nAI: I'll create a visualization of your sales trends.\n[Uses query_data and create_visualization tools]  \nHere's an interactive line chart showing your sales growth...\n\nYou: Export this data to Excel with detailed formatting\n\nAI: I'll export the sales data to Excel with metadata.\n[Uses export_excel tool]\nExported 1,247 rows to sales_trends_20241220_143022.xlsx...\n\nYou: What other insights can you find in this data?\n\nAI: Let me analyze the query results and suggest related insights.\n[Uses explain_results and suggest_related_queries tools]\nBased on your data, I found 3 key insights and suggest 5 related questions...\n```\n\n## 🎯 Advanced Use Cases\n\n### 📊 Business Intelligence\n```bash\n# Revenue Analysis Dashboard\n\"Create a dashboard showing monthly revenue, top products, and customer segments\"\n\n# Performance Optimization  \n\"Analyze my slowest queries and suggest optimizations\"\n\n# Automated Reporting\n\"Export quarterly sales data to Excel with charts and pivot tables\"\n```\n\n### 🔍 Data Exploration\n```bash\n# AI-Powered Discovery\n\"What interesting patterns do you see in my customer data?\"\n\n# Smart Suggestions\n\"Based on my order history, what questions should I ask next?\"\n\n# Context-Aware Analysis  \n\"Compare this month's performance with historical trends\"\n```\n\n### 🛡️ Enterprise Security\n```bash\n# User Management\n\"Create analyst users with read-only permissions\"\n\n# Audit Trail\n\"Show me all database modifications in the last week\"\n\n# Permission Management\n\"What databases can the current user access?\"\n```\n\n## 🏆 Key Advantages\n\n### 🚀 **Performance \u0026 Scalability**\n- **Redis caching** - Query results and schema cached for speed\n- **Connection pooling** - Efficient database resource management\n- **Async operations** - Non-blocking I/O for better throughput\n- **Smart optimization** - AI-powered query performance suggestions\n\n### 🔒 **Enterprise Security**\n- **Role-Based Access Control (RBAC)** - Fine-grained permissions\n- **Session management** - Secure user authentication\n- **SQL injection prevention** - Parameterized queries\n- **Audit logging** - Complete activity tracking\n\n### 🧠 **AI Intelligence**\n- **Context awareness** - Learns from query history\n- **Smart suggestions** - Proactive query recommendations  \n- **Result explanation** - Natural language insights\n- **Query optimization** - Performance improvement hints\n\n### 📈 **Rich Visualizations**\n- **Interactive charts** - Plotly-powered visualizations\n- **Smart recommendations** - AI suggests best chart types\n- **Dashboard creation** - Multi-chart dashboards\n- **Export capabilities** - Charts as PNG, SVG, PDF\n\n### 🔧 **Developer Experience**\n- **38 comprehensive tools** - Everything you need in one place\n- **Excellent error handling** - User-friendly error messages\n- **Comprehensive documentation** - Every tool documented\n- **Easy integration** - Works with any MCP client\n\n## 🎛️ Configuration Options\n\n### Feature Flags\nControl exactly which features are enabled:\n\n```bash\nENABLE_AUTHENTICATION=true    # User authentication\nENABLE_QUERY_CACHING=true     # Redis caching  \nENABLE_QUERY_HISTORY=true     # Session history\nENABLE_SMART_SUGGESTIONS=true # AI suggestions\nENABLE_VISUALIZATION=true     # Chart generation\n```\n\n### Performance Tuning\n```bash\nCACHE_TTL=300                 # Cache timeout (seconds)\nQUERY_TIMEOUT=30              # Query timeout (seconds)  \nMAX_RESULT_ROWS=1000          # Maximum rows returned\n```\n\n### Database Support\n```bash\nDB_TYPE=postgresql            # postgresql, mysql, sqlite\n```\n\n## 🏗️ Database Support Matrix\n\n| Database | Connection | Queries | Visualization | Export | Status |\n|----------|------------|---------|---------------|--------|---------|\n| PostgreSQL | ✅ | ✅ | ✅ | ✅ | Full Support |\n| MySQL | ✅ | ✅ | ✅ | ✅ | Full Support |\n| SQLite | ✅ | ✅ | ✅ | ✅ | Full Support |\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Server Won't Start?**\n```bash\n# Check Python version\npython --version  # Must be 3.9+\n\n# Install missing dependencies\npip install -r requirements.txt\npip install pydantic-settings\n\n# Check configuration\npython -c \"from src.core.config import config; print('Config OK')\"\n```\n\n**Database Connection Issues?**\n```bash\n# Test database connection\npython -c \"\nfrom src.database import create_database_manager\nimport asyncio\nasync def test():\n    db = create_database_manager('postgresql', {\n        'host': 'localhost', 'port': 5432, \n        'username': 'postgres', 'password': 'password', \n        'database': 'testdb'\n    })\n    print('Connected:', await db.connect())\nasyncio.run(test())\n\"\n```\n\n**AI Features Not Working?**\n- Verify OpenAI API key is valid\n- Check API quota and billing\n- Test with simple queries first\n\n**Visualizations Not Generated?**\n- Ensure matplotlib/plotly are installed\n- Check data format and column types\n- Try with smaller datasets first\n\n## 📊 Performance Benchmarks\n\n| Operation | Without Cache | With Cache | Improvement |\n|-----------|---------------|------------|-------------|\n| Schema Query | 150ms | 5ms | 30x faster |\n| Complex Query | 2.1s | 100ms | 21x faster |\n| Visualization | 800ms | 200ms | 4x faster |\n\n## 🛣️ Roadmap \u0026 Future Features\n\n### Phase 3 (Planned)\n- 🌐 **Web Interface** - Browser-based query interface\n- 📱 **Mobile API** - REST API for mobile applications  \n- 🔄 **Real-time Sync** - Live data synchronization\n- 🤖 **Advanced AI** - Custom model training\n- 📊 **More Databases** - MongoDB, Cassandra support\n\n### Phase 4 (Future)\n- ☁️ **Cloud Deployment** - AWS/GCP/Azure support\n- 🔐 **SSO Integration** - SAML/OAuth support\n- 📈 **Advanced Analytics** - ML-powered insights\n- 🌍 **Multi-language** - Support for multiple languages\n\n## 🤝 Contributing\n\nWe welcome contributions! Areas where you can help:\n\n- 🐛 Bug fixes and testing\n- 📚 Documentation improvements  \n- 🔧 New database adapters\n- 🎨 UI/UX enhancements\n- 🧪 Test coverage expansion\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🎉 Ready to Transform Your Database Experience?\n\nThis isn't just a tool—it's a complete database interaction revolution. With 38 powerful tools, enterprise-grade security, AI intelligence, and beautiful visualizations, you're equipped to handle any data challenge.\n\n**Start your journey today:**\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd db-rag\npip install -r requirements.txt\npython src/server.py\n```\n\n**Join thousands of developers, analysts, and enterprises who've revolutionized their database interactions!** 🚀\n\n---\n\n*Natural Language SQL MCP Server v2.0.0 - Making databases accessible to everyone* ✨","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulkit0111%2Fdb_rag_mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpulkit0111%2Fdb_rag_mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulkit0111%2Fdb_rag_mcp/lists"}