Skip to main content
This guide will walk you through setting up DBHub and connecting it to an AI tool for the first time. We’ll use demo mode to get started quickly, then show you how to connect to your own database.

​
Prerequisites

Before starting, ensure you have:
  • Node.js 18+ installed (for NPM method) OR Docker installed
  • Access to an AI tool (Claude Desktop, Claude Code, Cursor, or VS Code)
  • Optionally: A PostgreSQL, MySQL, or other supported database

​
Step 1: Start DBHub in Demo Mode

Let’s start with demo mode to verify everything works:
  • NPM
  • Docker
npx @bytebase/dbhub --transport stdio --demo
Demo mode includes a sample SQLite “employee” database with realistic data - perfect for testing without setting up a real database connection.
The server will start and display output indicating it’s ready to accept connections.

​
Step 2: Connect with Your AI Tool

Choose your AI tool and follow the setup instructions:

​
Claude Desktop

Edit your Claude Desktop configuration file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json
  • Docker Demo
  • NPX Demo
  • NPX with Your Database
claude_desktop_config.json
{
  "mcpServers": {
    "dbhub-demo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "bytebase/dbhub",
        "--transport",
        "stdio",
        "--demo"
      ]
    }
  }
}
Claude Desktop only supports stdio transport.

​
Cursor

Install DBHub in Cursor using the deeplink or manual configuration: Quick Install (Deeplink): 
cursor://anysphere.cursor-deeplink/mcp/install?name=dbhub&config=eyJjb21tYW5kIjoibnB4IEBieXRlYmFzZS9kYmh1YiIsImVudiI6eyJUUkFOU1BPUlQiOiJzdGRpbyIsIkRTTiI6InBvc3RncmVzOi8vdXNlcjpwYXNzd29yZEBsb2NhbGhvc3Q6NTQzMi9kYm5hbWU/c3NsbW9kZT1kaXNhYmxlIiwiUkVBRE9OTFkiOiJ0cnVlIn19
Copy the link above and paste it into your browser to install DBHub in Cursor. Manual Configuration: Configure in Cursor’s MCP settings or use environment variables: 
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "TRANSPORT": "stdio",
        "DSN": "postgres://user:password@localhost:5432/dbname?sslmode=disable",
        "READONLY": "true"
      }
    }
  }
}
Cursor supports both stdio and http transports. Make sure to use Agent mode to access MCP tools.

​
Claude Code

Create or update .claude/mcp.json in your project:
.claude/mcp.json
{
  "servers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp",
      "type": "http"
    }
  }
}
Start DBHub server with HTTP transport: 
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/mydb" --readonly
Claude Code uses HTTP transport. The server must be running before you can use it.

​
VS Code with Copilot

Create .vscode/mcp.json in your project:
.vscode/mcp.json
{
  "servers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp",
      "type": "http"
    }
  },
  "inputs": []
}
Start DBHub server: 
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/mydb" --readonly
Optional: Add Copilot Instructions Create .github/copilot-instructions.md to provide context:
.github/copilot-instructions.md
## Database Access

This project provides an MCP server (DBHub) for secure database access.

In read-only mode (recommended):
- `SELECT * FROM users LIMIT 10;`
- `SHOW TABLES;`
- `DESCRIBE table_name;`

Use the `execute_sql` tool to run queries.
VS Code with GitHub Copilot supports both stdio and http transports.

​
Step 3: Restart Your AI Tool

After updating the configuration:
  1. Claude Desktop/Cursor: Completely quit and restart the application
  2. Claude Code/VS Code: Reload the window or restart VS Code
  3. Verify the MCP server appears in the tools/resources list

​
Step 4: Try It Out

Try these example prompts in your AI tool: 
What schemas are available in the database?
Claude will use the db://schemas resource to list all schemas.
What tables are in the public schema?
Claude will use the db://schemas/public/tables resource.
Show me the top 5 employees by salary
Claude will generate and execute SQL like:
SELECT * FROM employees ORDER BY salary DESC LIMIT 5;

How many employees are in each department?
Claude will generate an appropriate SQL query:
SELECT dept_name, COUNT(*) as employee_count
FROM dept_emp
JOIN departments USING (dept_no)
WHERE to_date = '9999-01-01'
GROUP BY dept_name
ORDER BY employee_count DESC;

​
Step 5: Connect to Your Own Database

Once you’ve verified DBHub works in demo mode, connect it to your actual database:

​
Update Your Configuration

  • PostgreSQL
  • MySQL
  • SQLite
{
  "mcpServers": {
    "dbhub-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "postgres://user:password@localhost:5432/mydb?sslmode=disable",
        "--readonly"
      ]
    }
  }
}
We added --readonly flag for safety. This restricts the AI to only SELECT queries - perfect for production databases!

​
Using Environment Variables

For better security, avoid putting passwords in the config file:
  1. Create a .env file:
.env
DSN=postgres://user:password@localhost:5432/mydb?sslmode=disable
READONLY=true
  1. Update your configuration to use environment variables:
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio"],
      "env": {
        "DSN": "postgres://user:password@localhost:5432/mydb?sslmode=disable",
        "READONLY": "true"
      }
    }
  }
}

​
Common Use Cases

​
Explore Database Schema

Show me the structure of the users table
Claude will retrieve the table structure including columns, types, and constraints.

​
Generate SQL Queries

Write a query to find all users who signed up in the last 30 days
Claude will generate appropriate SQL based on your schema.

​
Data Analysis

Analyze the distribution of order amounts by customer segment
Claude will create and execute analytical queries to answer your question.

​
Debug Issues

Why is this query slow: SELECT * FROM orders WHERE customer_id = 123
Claude can examine indexes and suggest optimizations.

​
Next Steps

Multi-Database Setup

Connect to multiple databases simultaneously

Read-Only Mode

Secure your production databases

SSH Tunneling

Connect through bastion hosts

DSN Configuration

Database connection string formats

​
Troubleshooting

​
MCP Server Not Appearing

If the server doesn’t appear in Claude Desktop:
  1. Check the configuration file syntax (valid JSON)
  2. Verify the file path is correct
  3. Restart Claude Desktop completely
  4. Check Claude Desktop logs for errors

​
Connection Errors

If you see database connection errors:
  1. Verify your DSN is correct
  2. Test the connection using a database client
  3. Check firewall rules
  4. For Docker, use host.docker.internal instead of localhost

​
Permission Errors

If queries fail with permission errors:
  1. Verify the database user has the necessary permissions
  2. Check if the database requires SSL (add ?sslmode=require to DSN)
  3. Ensure the user can access the schema you’re querying