MCP server for all databases (based on JDBC)

3 months ago 1

Transform your database into an intelligent conversational partner. Ask questions in plain English, get instant answers, and create beautiful visualizations - all through Claude Desktop or any other MCP Client.

DBChat is a bridge that connects any MCP client like Claude Desktop, Gemini-CLI, etc to your database, enabling natural language database interactions. Instead of writing SQL queries, simply ask the chatbot questions about your data and get instant, intelligent responses.

Before DBChat:

SELECT c.name, COUNT(o.id) as order_count, SUM(o.total) as revenue FROM customers c LEFT JOIN orders o ON c.id = o.customer_id WHERE o.created_at >= '2024-01-01' GROUP BY c.id, c.name ORDER BY revenue DESC LIMIT 10;

With DBChat:

"Show me our top 10 customers by revenue this year"

🗣️ Natural Language Database Queries

Ask questions in plain English: "How many customers signed up last month?"
Get conversational responses: The LLM explains the data and provides insights
No SQL knowledge required: Perfect for business users and analysts

📊 Instant Data Visualizations

Automatic chart creation: Claude generates beautiful charts from your data
Multiple chart types: Line charts, bar charts, pie charts, scatter plots, and more
Interactive insights: Drill down into your data with follow-up questions

Database discovery: "What tables do we have?" "Show me the customer table structure"
Relationship understanding: The AI model explains how your tables connect
Data quality insights: Find duplicates, missing data, and anomalies

💼 Business Intelligence Made Easy

Executive dashboards: "Create a sales summary for our board meeting"
Trend analysis: "Show me user growth over the past 6 months"
Performance metrics: "Which products are underperforming?"

DBChat works with virtually any database (as long as it has a JDBC driver)

MySQL / MariaDB - Web applications and e-commerce
Oracle - Enterprise applications
PostgreSQL - Advanced applications and analytics
SQL Server - Microsoft environments
H2 - Testing and development
SQLite - Local applications and prototypes
HSQLDB - Testing and development

Redis - In-memory data store
MongoDB - Document-oriented database
Cassandra - Wide-column store

Snowflake - Cloud data platform
Databricks - Cloud data platform
Amazon Redshift - AWS data warehouse
Google BigQuery - Google analytics
ClickHouse - Real-time analytics

CSV Files - Spreadsheet data and exports
Excel Files - Can be exported to CSV and queried

See INSTALL.md for the complete list and build options.

Download the latest release from GitHub Releases:

dbchat-3.0.0-basic.jar - Basic version (PostgreSQL, SQLite, H2, HSQLDB, CSV) <-- Start here
dbchat-3.0.0-standard.jar - Standard version (add MySQL, MariaDB, ClickHouse)
dbchat-3.0.0-enterprise.jar - Enterprise version (add Oracle, SQL Server, DB2)
dbchat-3.0.0-cloud-analytics.jar - Cloud Analytics version (add Redshift, Snowflake, BigQuery)
dbchat-3.0.0-all.jar - All databases included (400MB+)

(Optional) For simplicity rename the downloaded file to dbchat-3.0.0.jar so you can follow the rest of the commands here without needing to adjust them to your version.

mv dbchat-3.0.0.jar dbchat.jar OR ren dbchat-3.0.0.jar dbchat.jar

NOTE: Advanced users can also build a custom jar with only the drivers you need. See INSTALL.md for details.

IMPORTANT: Make sure that you are properly LICENSED to use any JDBC driver you install. The DBChat license does not cover any third party code or binaries.

Step 2: Install Claude Desktop (similar setup for any other MCP client)

Download Claude Desktop (free)
Sign in with your Claude account
Important: The Claude website does not support MCP. For MCP only with Anthropic models you need to use Claude Desktop.

If you are not using Claude Desktop but want to use another MCP client like Cursor, Windsurf, VS Code, Continue, etc then please refer to the MCP Setup document for more details

Step 3: Set Up Your Database Connection

Create a configuration file dbchat.conf:

# Basic database connection DB_URL=jdbc:mysql://localhost:3306/your_database DB_USER=your_username DB_PASSWORD=your_password DB_DRIVER=com.mysql.cj.jdbc.Driver # Optional: Enable web interface (not needed for Claude desktop) HTTP_MODE=false HTTP_PORT=8080

Examples for Common/Popular Databases:

MySQL:

DB_URL=jdbc:mysql://localhost:3306/your_database DB_USER=your_username DB_PASSWORD=your_password DB_DRIVER=com.mysql.cj.jdbc.Driver

PostgreSQL:

DB_URL=jdbc:postgresql://localhost:5432/your_database DB_USER=your_username DB_PASSWORD=your_password DB_DRIVER=org.postgresql.Driver

SQLite:

DB_URL=jdbc:sqlite:/path/to/your/database.db DB_USER= DB_PASSWORD= DB_DRIVER=org.sqlite.JDBC

H2 database (in memory - no database setup required):

DB_URL=jdbc:h2:mem:testdb DB_USER=sa DB_PASSWORD= DB_DRIVER=org.h2.Driver

Oracle:

DB_URL=jdbc:oracle:thin:@localhost:1521:xe DB_USER=system DB_PASSWORD=password DB_DRIVER=oracle.jdbc.driver.OracleDriver

Redis:

DB_URL=jdbc:redis://localhost:6379 DB_USER= DB_PASSWORD=your_redis_password DB_DRIVER=com.dbvis.jdbc.redis.RedisDriver

Step 4: Configure Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
Add your database server:

{ "mcpServers": { "database": { "command": "java", "args": [ "-jar", "/absolute/path/to/dbchat-3.0.0.jar", "--config_file=/absolute/path/to/dbchat.conf" ] } } }

Alternative without config file:

{ "mcpServers": { "database": { "command": "java", "args": ["-jar", "/absolute/path/to/dbchat-3.0.0.jar"], "env": { "DB_URL": "jdbc:mysql://localhost:3306/your_database", "DB_USER": "your_username", "DB_PASSWORD": "your_password", "DB_DRIVER": "com.mysql.cj.jdbc.Driver" } } } }

Windows Example:

{ "mcpServers": { "database": { "command": "java", "args": [ "-jar", "C:/Users/YourName/Downloads/dbchat-3.0.0.jar", "--config_file=C:/Users/YourName/dbchat.conf" ] } } }

NOTE: If java is not in your PATH then use the full path to java (JDK 17+) in the command.

Step 5: Connect Multiple Databases

You can use many databases concurrently!

{ "mcpServers": { "production-db": { "command": "java", "args": ["-jar", "/path/to/dbchat-3.0.0.jar"], "env": { "DB_URL": "jdbc:mysql://prod-server:3306/production", "DB_USER": "readonly_user", "DB_PASSWORD": "secure_password", "DB_DRIVER": "com.mysql.cj.jdbc.Driver", "SELECT_ONLY": "true" } }, "analytics-db": { "command": "java", "args": ["-jar", "/path/to/dbchat-3.0.0.jar"], "env": { "DB_URL": "jdbc:postgresql://analytics:5432/warehouse", "DB_USER": "analyst", "DB_PASSWORD": "password", "DB_DRIVER": "org.postgresql.Driver" } } } }

Step 6: Restart Claude Desktop

Close and reopen Claude Desktop. You should see a database connection indicator in the chat input.

💬 Start Talking to Your Database

"What tables do we have in the database?" "Show me the structure of the customers table" "How many records are in each table?"

"How many new customers did we get last month?" "What are our top 5 selling products this quarter?" "Show me revenue by month for the past year"

"Find customers who haven't ordered in 6 months" "Are there any duplicate email addresses?" "What's the average order value by customer segment?"

"Create a chart showing monthly sales trends" "Make a pie chart of orders by product category" "Show me a bar chart of customer signups by region"

"Calculate customer lifetime value for each segment" "Identify seasonal trends in our sales data" "Find correlations between customer age and purchase behavior"

📱 More Real-World Examples

"Show me our conversion funnel from visitors to purchases" "Which products have the highest return rates?" "Create a dashboard showing daily sales performance"

"Find customers at risk of churning" "Show me customer satisfaction trends" "Identify our most valuable customer segments"

"Generate a P&L summary for this quarter" "Show cash flow trends over the past 12 months" "Create an expense breakdown by department"

"Monitor inventory levels across all warehouses" "Show shipping performance by carrier" "Identify bottlenecks in our fulfillment process"

📊 Data Visualization Examples

DBChat enables Claude to create stunning visualizations directly from your database:

Monthly Revenue Trends: Line charts showing growth over time
Top Products: Bar charts of bestsellers
Regional Performance: Heat maps of sales by location
Customer Segments: Pie charts of revenue distribution

User Growth: Area charts showing acquisition trends
Performance Metrics: Multi-axis charts combining different KPIs
Comparative Analysis: Side-by-side visualizations of different periods

Inventory Levels: Real-time stock visualization
System Performance: Time-series charts of key metrics
Quality Metrics: Statistical charts showing trends and outliers

Protect your data with read-only access:

Control resource usage:

MAX_ROWS_LIMIT=1000 QUERY_TIMEOUT_SECONDS=30 MAX_SQL_LENGTH=10000

All data stays on your machine
No external API calls
Encrypted environment variables
Secure local communication

🌐 Web Interface (Optional)

Enable HTTP mode for web-based access:

# Turn on HTTP listener HTTP_MODE=true # Listen on port 8080 HTTP_PORT=8080 # Bind to all interfaces (allows external access) BIND_ADDRESS=0.0.0.0 # NOTE: If no bind address is given we bind to localhost only (default, most secure)

Then access at http://localhost:8080/. For example try http://localhost:8080/health to check health status

For similar config via CLI args use:

# Bind to localhost only (default, most secure) java -jar dbchat-3.0.0.jar --http_mode=true --http_port=8080 # Bind to all interfaces (allows external access) java -jar dbchat-3.0.0.jar --http_mode=true --bind_address=0.0.0.0 --http_port=8080 # Bind to specific interface java -jar dbchat-3.0.0.jar --http_mode=true --bind_address=192.168.1.100 --http_port=8080

🔧 Configuration Methods and Priority

For maximum flexibility, DBChat supports multiple configuration methods like CLI arguments, config file, Environment vars, System Properties and Built-in Defaults. Understanding the priority order is crucial for troubleshooting and advanced setups.

Configuration Priority Order (Highest to Lowest)

Command Line Arguments (Highest Priority)
Configuration File
Environment Variables
System Properties
Built-in Defaults (Lowest Priority)

This means command line arguments will always override config files, which override environment variables, and so on.

Method 1: Command Line Arguments

Format: --parameter_name=value Use case: Quick overrides, testing, one-time configurations

java -jar dbchat-3.0.0.jar \ --db_url="jdbc:mysql://localhost:3306/mydb" \ --db_user="username" \ --db_password="password" \ --db_driver="com.mysql.cj.jdbc.Driver" \ --http_mode=true \ --http_port=8080 \ --select_only=true

Available parameters:

--config_file=/path/to/config.conf
--db_url="jdbc:..."
--db_user="username"
--db_password="password"
--db_driver="com.mysql.cj.jdbc.Driver"
--http_mode=true
--http_port=8080
--max_connections=20
--connection_timeout_ms=30000
--query_timeout_seconds=60
--select_only=true
--max_sql_length=50000
--max_rows_limit=10000

Method 2: Configuration Files

Format: KEY=VALUE (one per line) Use case: Production environments, complex configurations, version control

Create a file (e.g., dbchat.conf):

# Database Connection DB_URL=jdbc:postgresql://localhost:5432/myapp DB_USER=dbuser DB_PASSWORD=my secure password with spaces DB_DRIVER=org.postgresql.Driver # Connection Pool Settings MAX_CONNECTIONS=20 CONNECTION_TIMEOUT_MS=60000 IDLE_TIMEOUT_MS=300000 MAX_LIFETIME_MS=1800000 LEAK_DETECTION_THRESHOLD_MS=60000 # Query Settings QUERY_TIMEOUT_SECONDS=45 SELECT_ONLY=false MAX_SQL_LENGTH=50000 MAX_ROWS_LIMIT=50000 # Server Settings HTTP_MODE=true HTTP_PORT=8080

Usage:

java -jar dbchat-3.0.0.jar --config_file=dbchat.conf

Config file features:

Comments start with #
Empty lines are ignored
Values can be quoted: DB_PASSWORD="password with spaces"
Keys are case-insensitive
Supports all the same parameters as command line

Method 3: Environment Variables

Format: UPPERCASE_WITH_UNDERSCORES Use case: Docker, cloud deployment, CI/CD, secure credential management

export DB_URL="jdbc:mysql://localhost:3306/mydb" export DB_USER="username" export DB_PASSWORD="password" export DB_DRIVER="com.mysql.cj.jdbc.Driver" export HTTP_MODE="true" export HTTP_PORT="8080" export SELECT_ONLY="true" java -jar dbchat-3.0.0.jar

All environment variables:

CONFIG_FILE - Path to configuration file
DB_URL - Database connection URL
DB_USER - Database username
DB_PASSWORD - Database password
DB_DRIVER - JDBC driver class
HTTP_MODE - Enable HTTP mode (true/false)
HTTP_PORT - HTTP server port
MAX_CONNECTIONS - Connection pool size
CONNECTION_TIMEOUT_MS - Connection timeout
QUERY_TIMEOUT_SECONDS - Query timeout
SELECT_ONLY - Read-only mode (true/false)
MAX_SQL_LENGTH - Maximum query length
MAX_ROWS_LIMIT - Maximum result rows
IDLE_TIMEOUT_MS - Connection idle timeout
MAX_LIFETIME_MS - Connection max lifetime
LEAK_DETECTION_THRESHOLD_MS - Leak detection threshold

Method 4: System Properties

Format: -Dparameter.name=value (underscores become dots) Use case: JVM-specific configuration, IDE run configurations

java -Ddb.url="jdbc:mysql://localhost:3306/mydb" \ -Ddb.user="username" \ -Ddb.password="password" \ -Ddb.driver="com.mysql.cj.jdbc.Driver" \ -Dhttp.mode="true" \ -Dhttp.port="8080" \ -jar dbchat-3.0.0.jar

Property naming: Environment variable DB_URL becomes system property db.url

Method 5: Built-in Defaults

When: No configuration provided Values: Safe defaults for development

DB_URL=jdbc:h2:mem:testdb DB_USER=sa DB_PASSWORD= DB_DRIVER=org.h2.Driver HTTP_MODE=false HTTP_PORT=8080 MAX_CONNECTIONS=10 CONNECTION_TIMEOUT_MS=30000 QUERY_TIMEOUT_SECONDS=30 SELECT_ONLY=true MAX_SQL_LENGTH=10000 MAX_ROWS_LIMIT=10000

Example 1: Priority Override

# Config file has HTTP_PORT=8080 echo "HTTP_PORT=8080" > config.conf # Environment variable sets different port export HTTP_PORT=9090 # Command line overrides both java -jar dbchat-3.0.0.jar --config_file=config.conf --http_port=7070 # Result: Uses port 7070 (command line wins)

Example 2: Mixed Configuration

# Use config file for database settings echo "DB_URL=jdbc:mysql://localhost:3306/mydb" > prod.conf echo "DB_USER=produser" >> prod.conf echo "SELECT_ONLY=true" >> prod.conf # Override password via environment (more secure) export DB_PASSWORD="secure_password" # Override port via command line (for this run only) java -jar dbchat-3.0.0.jar --config_file=prod.conf --http_port=9090

Example 3: Claude Desktop Configuration

Note that most MCP clients use a similar configuration, but you'll need to refer to your MCP client docs for details on how it can be configured. It is safest not to assume any PATH settings and provide absolute paths for java, the dbchat jar and (optionally) the dbchat config file.

{ "mcpServers": { "database": { "command": "java", "args": [ "-jar", "/path/to/dbchat-3.0.0.jar", "--config_file=/path/to/production.conf", "--select_only=true" ], "env": { "DB_PASSWORD": "secure_password_from_env" } } } }

Configuration Parameters Reference

DB_URL - JDBC connection string (required)
DB_USER - Database username
DB_PASSWORD - Database password
DB_DRIVER - JDBC driver class (required)

MAX_CONNECTIONS=10 - Maximum concurrent connections
CONNECTION_TIMEOUT_MS=30000 - Connection acquisition timeout
IDLE_TIMEOUT_MS=600000 - Connection idle timeout (10 minutes)
MAX_LIFETIME_MS=1800000 - Connection max lifetime (30 minutes)
LEAK_DETECTION_THRESHOLD_MS=60000 - Connection leak detection (1 minute)

QUERY_TIMEOUT_SECONDS=30 - SQL query execution timeout
SELECT_ONLY=true - Read-only mode (blocks INSERT/UPDATE/DELETE)
MAX_SQL_LENGTH=10000 - Maximum characters in SQL query
MAX_ROWS_LIMIT=10000 - Maximum rows returned per query

HTTP_MODE=false - Enable HTTP web interface
HTTP_PORT=8080 - HTTP server port

# Good: Use environment variables for passwords export DB_PASSWORD="secure_password" java -jar dbchat-3.0.0.jar --config_file=app.conf # Good: Use config file with restricted permissions chmod 600 secure.conf java -jar dbchat-3.0.0.jar --config_file=secure.conf # Avoid: Passwords in command line (visible in process list) java -jar dbchat-3.0.0.jar --db_password="visible_password"

Configuration File Security

# Create secure config file umask 077 cat > secure.conf << EOF DB_PASSWORD=secure_password EOF # Verify permissions ls -la secure.conf # Should show: -rw------- (owner read/write only)

Troubleshooting Configuration

Check Effective Configuration

Enable debug logging to see which values are being used:

java -Dlogging.level.root=DEBUG -jar dbchat-3.0.0.jar --config_file=myconfig.conf

Config file not found: Use absolute paths
Permission denied: Check file permissions
Wrong values used: Check priority order
Environment variables not set: Use env | grep DB_ to verify

Claude Desktop Not Connecting

Check paths: Use absolute paths in configuration
Java version: Ensure Java 17+ is installed
File permissions: Verify JAR file is readable
Restart Claude: Close and reopen Claude Desktop

Database Connection Issues

Test connection: Verify database is running
Check credentials: Ensure username/password are correct
Network access: Confirm database allows connections
Driver support: Use the correct JAR version for your database

Limit results: Use MAX_ROWS_LIMIT=1000
Query timeout: Set QUERY_TIMEOUT_SECONDS=30
Connection pool: Adjust MAX_CONNECTIONS=10

"ClassNotFoundException"

Download the correct JAR version for your database
Check that the database driver is included

"Connection refused"

Verify database server is running
Check connection URL, username, and password
Ensure database allows connections from your machine

"Server not responding"

Check Claude Desktop configuration syntax
Verify Java is accessible in PATH
Review Claude Desktop logs

Start with read-only: Use SELECT_ONLY=true initially
Test with sample data: Try the H2 database first
Begin with simple questions: Start with basic table exploration
Build complexity gradually: Move to advanced analytics over time

Use dedicated database users: Create read-only users for DBChat
Limit access: Only grant necessary table permissions
Monitor usage: Review query logs regularly
Backup data: Always maintain database backups

Set reasonable limits: Use MAX_ROWS_LIMIT and timeouts
Index important columns: Ensure queries can run efficiently
Monitor resources: Watch CPU and memory usage
Optimize queries: Let Claude suggest query improvements

Model Context Protocol: modelcontextprotocol.io
Claude Desktop: claude.ai/download
Developer Guide: See INSTALL.md for technical details
GitHub Repository: github.com/skanga/dbchat

🚀 Ready to Transform Your Data Experience?

Download the appropriate JAR file for your database(s)
Install Claude Desktop (free)
Configure your database connection
Add DBChat to Claude Desktop settings
Start asking questions about your data!

Transform your relationship with data. No more complex SQL queries, no more waiting for reports. Just natural conversations with your database, powered by Claude's intelligence and DBChat's seamless integration.

Get started today and discover what your data has been trying to tell you.

Read Entire Article