Database MCP Server
A remote web-based Model Context Protocol (MCP) server that provides comprehensive database tools for both Supabase and general PostgreSQL databases. This server allows AI assistants like Claude and Cursor to interact with PostgreSQL databases through natural language.
🚀 Features
🔐 User-Provided Database Credentials
- Secure Web Form - Users provide their own database credentials through a beautiful, responsive web interface
- Multi-Database Support - Works with any PostgreSQL database including Supabase, AWS RDS, Google Cloud SQL, etc.
- No Shared Databases - Each user connects to their own database with their own credentials
- Real-time Validation - Instant validation of connection parameters and database connectivity
- Encrypted Storage - Database credentials are encrypted and only used for the user's session
Core Database Tools
list_tables- List all tables in specified schemaslist_extensions- List all PostgreSQL extensions installed in the databaselist_migrations- List all migrations applied to the database (supports common migration patterns)apply_migration- Apply SQL migrations (DDL operations with tracking)execute_sql- Execute any raw SQL statement for data queries or updatesquery- Run read-only SQL queries (legacy tool)
Additional Tools
- Steampipe Integration - Table and plugin management tools
- GitHub Authentication - OAuth-based user authentication
- Connection Testing - Automatic database connection validation
🏗️ Architecture
This MCP server is built on Cloudflare Workers and features:
Authentication Flow
- User Authorization - Users access the MCP server through their AI assistant (Claude, Cursor, etc.)
- Database Credentials Form - Users fill out a secure web form with their database connection details
- GitHub OAuth - Users authenticate via GitHub for identity verification
- Secure Connection - Individual database pools are created per user with their provided credentials
Key Features
- Remote deployment on Cloudflare Workers or Railway
- No shared databases - Each user connects to their own database
- Per-user database pools with connection management
- Both Supabase and general PostgreSQL database support
- Secure credential handling with encryption and validation
📋 Prerequisites
- Node.js 18+
- A Cloudflare account (for Cloudflare Workers deployment)
- A GitHub account (for OAuth setup)
- A PostgreSQL or Supabase database
🛠️ Setup
1. Clone and Install
git clone <your-repo-url>
cd database-mcp
npm install
2. GitHub OAuth Application Setup
Create a GitHub OAuth App for authentication:
- Go to GitHub → Settings → Developer Settings → OAuth Apps
- Click "New OAuth App"
- Fill in the details:
- Application name:
Database MCP Server - Homepage URL:
https://your-worker-name.your-account.workers.dev - Authorization callback URL:
https://your-worker-name.your-account.workers.dev/callback
- Application name:
3. Environment Variables
Set up the following environment variables in your Cloudflare Worker:
| Variable Name | Type | Description | Example |
|---|---|---|---|
DATABASE_URL | Secret | PostgreSQL connection string | postgresql://user:password@host:5432/database |
GITHUB_CLIENT_ID | Secret | GitHub OAuth App Client ID | your_github_client_id |
GITHUB_CLIENT_SECRET | Secret | GitHub OAuth App Client Secret | your_github_client_secret |
COOKIE_ENCRYPTION_KEY | Secret | Random key for cookie encryption | openssl rand -hex 32 |
ALLOWED_USERNAMES | Secret | Comma-separated GitHub usernames | user1,user2,user3 |
Setting Secrets via Wrangler CLI:
npx wrangler secret put DATABASE_URL
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler secret put ALLOWED_USERNAMES
4. Deploy to Cloudflare Workers
npm run deploy
🔧 Usage
Connecting to AI Clients
Claude Desktop
- Install the mcp-remote proxy
- Update your Claude Desktop configuration:
{
"mcpServers": {
"database-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-worker-name.your-account.workers.dev/sse"
]
}
}
}
Cursor AI
Add to your MCP configuration:
{
"mcpServers": {
"database-mcp": {
"url": "https://your-worker-name.your-account.workers.dev/sse"
}
}
}
Cloudflare AI Playground
- Go to https://playground.ai.cloudflare.com/
- Enter your MCP server URL:
https://your-worker-name.your-account.workers.dev/sse - Authenticate with GitHub
- Start using the database tools!
Database Connection
The server supports both Supabase and general PostgreSQL databases. Users provide their own database credentials through the DATABASE_URL environment variable.
Supabase Connection String Format:
postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
General PostgreSQL Connection String Format:
postgresql://username:password@hostname:port/database_name
🔍 Available Tools
Core Database Operations
list_tables
Lists all tables in specified schemas.
Parameters:
- schemas (optional): Array of schema names (default: ["public"])
list_extensions
Lists all PostgreSQL extensions installed in the database.
No parameters required.
list_migrations
Lists all migrations applied to the database. Supports common migration table patterns:
supabase_migrations.schema_migrationspublic.schema_migrationspublic.migrations- And more...
apply_migration
Applies a SQL migration with automatic tracking.
Parameters:
- name: Migration name in snake_case
- query: SQL migration query (DDL operations only)
execute_sql
Executes any raw SQL statement.
Parameters:
- sql: The SQL statement to execute
- read_only (optional): Execute in read-only mode (default: false)
query
Runs read-only SQL queries (legacy tool).
Parameters:
- sql: The SQL query to execute
🚀 Deployment Options
Cloudflare Workers (Recommended)
- Deploy:
npm run deploy - Set secrets: Use
wrangler secret putcommands - Configure OAuth: Update GitHub OAuth app URLs
- Test: Visit your worker URL
Railway (Alternative)
- Connect your GitHub repository to Railway
- Set environment variables in Railway dashboard
- Deploy automatically on git push
🔒 Security
- OAuth Authentication: Only authorized GitHub users can access the tools
- User Allowlist: Configure specific GitHub usernames in
ALLOWED_USERNAMES - Connection Security: All database connections use secure connection strings
- Read-only Options: Tools support read-only execution modes
- Transaction Safety: Automatic rollback on errors
🛠️ Development
Local Development
npm run dev
Type Checking
npx tsc --noEmit
Generate Types
npm run cf-typegen
📚 Examples
List all tables in public schema
-- This will be executed via the list_tables tool
-- No direct SQL needed, just call the tool through your AI client
Execute a data query
-- Use execute_sql tool
SELECT * FROM users WHERE created_at > '2024-01-01';
Apply a migration
-- Use apply_migration tool with name: "add_user_email_index"
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
📄 License
MIT License - see LICENSE file for details.
🆘 Troubleshooting
Common Issues
-
"Database pool not initialized"
- Check your
DATABASE_URLenvironment variable - Ensure the connection string is valid
- Check your
-
"OAuth authentication failed"
- Verify GitHub OAuth app configuration
- Check
GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRET
-
"User not authorized"
- Add your GitHub username to
ALLOWED_USERNAMES - Ensure the username is spelled correctly
- Add your GitHub username to
-
Connection timeout
- Check database server accessibility
- Verify firewall settings
- Ensure SSL/TLS configuration is correct
Getting Help
- Check the Cloudflare Workers documentation
- Review the Model Context Protocol specification
- Open an issue in this repository
Built with ❤️ for the AI community. This MCP server bridges the gap between AI assistants and database management, making database operations accessible through natural language.
