If you have ever pasted a database schema into a chat window just so an AI could write a query, the DBHub MCP server removes that friction entirely. It is a single gateway that lets Claude, Cursor, VS Code, and any other Model Context Protocol client read your schema, run SQL, and explore data directly. This tutorial walks through installing it, wiring it into Claude Desktop, running safe queries, and locking it down for production-adjacent use.
The target reader is an intermediate developer who already works with Postgres, MySQL, or SQLite and wants their AI assistant to answer questions against real data instead of guessing. By the end, you will have a working setup, an understanding of read-only safety controls, and a clear sense of when this approach helps and when it gets you into trouble.
What Is the DBHub MCP Server?
The DBHub MCP server is a lightweight gateway, built by Bytebase, that implements the Model Context Protocol so AI clients can connect to a SQL database through one standard interface. It speaks to PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite, exposing schema exploration and query execution as MCP tools and resources that any compatible agent can call.
In plain terms, MCP is the contract and DBHub is the adapter. Your AI client never talks to the database driver directly. Instead, it asks DBHub to list tables or run a query, and DBHub translates that request into the right dialect for whichever database you pointed it at. Because the protocol is standardized, the same setup works whether you drive it from Claude Desktop, Cursor, or a custom agent.
If the protocol itself is new to you, our guide on the MCP protocol explained covers the fundamentals before you go further here.
Why Connect an AI Agent to Your Database?
The day-to-day value shows up fast. Instead of describing your schema to an assistant, you let it inspect the real tables, columns, and indexes. Therefore the SQL it writes matches your actual structure rather than a plausible guess. That difference matters most on schemas with dozens of tables and non-obvious foreign keys.
There are three common jobs this unlocks. First, ad-hoc data questions (“how many orders shipped late last month?”) become a sentence rather than a hand-written join. Second, schema-aware code generation improves, because the agent can confirm column names before it suggests an ORM model. Third, debugging gets faster, since the assistant can inspect actual rows when a query returns something unexpected.
Supported Databases at a Glance
DBHub handles the major relational engines through one binary. The connection string format changes per engine, but the tools your agent calls stay identical.
| Database | DSN Prefix | Common Use |
|---|---|---|
| PostgreSQL | postgres:// | Web apps, analytics, JSONB workloads |
| MySQL | mysql:// | Legacy and CMS-backed apps |
| MariaDB | mariadb:// | MySQL-compatible deployments |
| SQL Server | sqlserver:// | Enterprise and .NET stacks |
| SQLite | sqlite:// | Local files, embedded apps, prototypes |
Because the tool surface is uniform, you can point DBHub at a local SQLite file while prototyping and switch to Postgres in a shared environment without changing how your agent calls it.
Prerequisites
You need a few things in place before the first run. Keeping these tight avoids the most common setup failures.
- Node.js 22.5.0 or newer if you plan to run DBHub through
npx(or Docker as an alternative) - A reachable database and a connection string with credentials
- An MCP client such as Claude Desktop, Cursor, or VS Code with MCP support
- A database user scoped to the least privilege you need — ideally read-only
That last point is not optional advice. The fastest way to stay safe is to hand DBHub a database role that physically cannot write, rather than relying only on software flags.
Step 1: Run the DBHub MCP Server
The quickest way to confirm everything works is demo mode, which spins up a sample SQLite database with employee data. Run it over HTTP so you can poke at the built-in web workbench in a browser.
# Launch DBHub in demo mode on http://localhost:8080
npx @bytebase/dbhub@latest --transport http --port 8080 --demo
Open http://localhost:8080 and you will see the workbench, a visual interface for browsing the sample schema and running queries without any MCP client attached. This is the fastest sanity check that the binary runs on your machine.
Once that works, point it at a real database with a DSN. The example below connects to a local Postgres instance in read-only mode.
# Connect to Postgres, read-only, over HTTP
npx @bytebase/dbhub@latest \
--transport http \
--port 8080 \
--readonly \
--dsn "postgres://readonly_user:password@localhost:5432/appdb?sslmode=disable"
If you prefer containers, Docker takes the same flags. This is the cleaner option for shared dev environments because it avoids a global Node dependency.
# Same server via Docker
docker run --rm --init \
--name dbhub \
--publish 8080:8080 \
bytebase/dbhub \
--transport http \
--port 8080 \
--readonly \
--dsn "postgres://readonly_user:password@host.docker.internal:5432/appdb?sslmode=disable"
Note the --readonly flag in both commands. It instructs DBHub to reject anything that mutates data, which we will examine more closely in the safety section.
Step 2: Connect DBHub to Claude Desktop
For desktop AI clients, the stdio transport is the right choice. Rather than running a long-lived HTTP server, the client launches DBHub as a child process and talks to it over standard input and output. You configure this in Claude Desktop’s MCP settings file.
On macOS the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is at %APPDATA%\Claude\claude_desktop_config.json. Add a dbhub entry under mcpServers.
{
"mcpServers": {
"dbhub": {
"command": "npx",
"args": [
"-y",
"@bytebase/dbhub@latest",
"--transport", "stdio",
"--readonly",
"--dsn", "postgres://readonly_user:password@localhost:5432/appdb?sslmode=disable"
]
}
}
}
Here the command is npx and every flag becomes an entry in the args array, because Claude Desktop passes them straight to the spawned process. After saving, restart Claude Desktop fully. The DBHub tools should then appear in the client’s tool list, ready for the model to call.
If you are setting up MCP servers for the Claude Code CLI instead of the desktop app, the pattern is similar but configured differently — see our walkthrough on configuring MCP servers in Claude Code.
Step 3: Ask Your First Questions
With the server connected, you can now ask data questions in natural language. The model decides which DBHub tool to call and how to phrase the SQL. A first prompt might be: “List the tables in this database and describe the orders table.”
Behind that request, the agent calls DBHub’s schema-exploration capabilities. DBHub exposes two primary tools that do the work:
execute_sqlruns a SQL query and returns the rows, with transaction support and the safety controls discussed below.search_objectsexplores database structure — schemas, tables, columns, indexes, and stored procedures — so the agent can ground its SQL in the real layout.
In addition, DBHub publishes the schema as MCP resources. Resources are read-only context the client can pull in without a tool call, such as the list of schemas or the column definitions for a given table. The practical effect is that a capable agent inspects structure first, then writes a query that actually compiles.
A realistic follow-up prompt shows the value: “Which customers placed more than five orders last quarter, and what was their total spend?” The agent reads the relevant tables, writes the join and aggregation, runs it through execute_sql, and returns the answer. You never typed a line of SQL, yet the query is grounded in your real schema.
Understanding Read-Only Mode and Safety Controls
Giving an AI a SQL connection is powerful, which means it is also where most of the risk lives. DBHub ships several controls, and you should treat them as layered rather than relying on any single one.
The --readonly flag is the headline control. When enabled, DBHub permits read operations such as SELECT and rejects statements that modify data or schema, like INSERT, UPDATE, DELETE, and DROP. As a result, a model that hallucinates a destructive query simply gets an error instead of dropping a table.
Beyond that, DBHub supports row limiting and query timeouts. Row limits cap how many rows a single query can return, which prevents an agent from accidentally pulling millions of records into context. Query timeouts kill long-running statements before they exhaust a connection or lock a table. For network security, the server also supports SSH tunneling and SSL/TLS, so you are not exposing raw database ports.
Even with all of that, the strongest defense is a database role with no write permission. Software flags protect against mistakes; a read-only role protects against bugs in the flags themselves. Use both. Our guide on preventing SQL injection with parameterized queries is worth a read here, since an AI generating raw SQL raises similar input-trust questions.
Connecting to Multiple Databases
Real projects rarely have just one database. DBHub supports managing several connections through a TOML configuration file, so your agent can switch between, say, a Postgres analytics replica and a SQLite reporting cache without you restarting anything.
# dbhub.toml — multiple named connections
[connections.analytics]
dsn = "postgres://readonly_user:password@analytics-replica:5432/metrics?sslmode=require"
readonly = true
[connections.local_reports]
dsn = "sqlite:///var/data/reports.db"
readonly = true
You then start DBHub pointing at the config file rather than a single DSN, and each connection becomes selectable. This keeps credentials in one managed place instead of scattered across shell history. For analytics workloads specifically, point DBHub at a read replica rather than your primary — the agent’s exploratory queries should never compete with production traffic.
Real-World Scenario: A Read-Only Analytics Assistant
Consider a small data team at a mid-sized SaaS company with a Postgres database of roughly 40 tables. Non-engineers constantly ask the two backend developers for “quick” numbers — churn last month, top accounts by usage, signups by plan. Each request interrupts deep work, and the answers are simple joins the developers could write in their sleep.
The team stands up a DBHub MCP server against a read-only replica, with --readonly enabled and a row limit set. They connect it to a shared Claude Desktop setup for the analysts. Over the following weeks, the pattern that emerges is telling: the syntax was never the hard part, but the schema knowledge was. Analysts who understood the business but not the table structure can now self-serve, because the agent inspects the schema for them.
The trade-off appears too. The agent occasionally writes a technically correct query that misreads business intent — counting soft-deleted rows, for instance, because nothing in the schema flagged them. That is the limitation worth internalizing: DBHub gives an agent access and structure, but not the institutional context that lives in people’s heads. The fix was a short prompt convention reminding the model about the deleted_at column, not a tooling change.
When to Use the DBHub MCP Server
- You want an AI assistant to answer ad-hoc data questions grounded in your real schema
- Your team frequently writes exploratory
SELECTqueries and wants to speed that up - You can provide a read-only database role or replica, keeping production write paths untouched
- You work across several SQL engines and want one consistent interface for all of them
- You are prototyping an agent that needs database context and want a standard MCP integration
When NOT to Use the DBHub MCP Server
- You need the agent to perform writes or migrations as part of an automated pipeline — that demands far stricter guardrails than a chat tool
- Your database holds sensitive personal data that should never enter an LLM’s context window
- You require deterministic, version-controlled queries; AI-generated SQL is not a substitute for a reviewed reporting layer
- You only ever query a single, simple table where a saved query is faster than a round trip through an agent
Common Mistakes with the DBHub MCP Server
- Running without
--readonlyagainst a production database, trusting the model not to issue destructive SQL - Granting the DSN a full-privilege role instead of a scoped read-only user, leaving software flags as the only barrier
- Pointing the server at a primary database so exploratory queries compete with live traffic, instead of a replica
- Exposing the HTTP transport on a public interface rather than binding to
127.0.0.1behind a reverse proxy - Forgetting row limits, which lets a broad
SELECT *pull huge result sets into the model’s context and inflate token costs
That last point connects to a broader habit worth building. If you are wiring databases into agents regularly, the same discipline around tools and execution applies — our guide on building AI agents with tools, planning, and execution covers how to scope agent capabilities deliberately.
How Does DBHub Compare to Text-to-SQL Tools?
DBHub is plumbing, not a finished text-to-SQL product. It exposes raw database access over MCP and lets whatever model you connect decide how to use it. Dedicated text-to-SQL systems, by contrast, add semantic layers, query validation, and a chat UI on top.
If your goal is a polished natural-language analytics product, a purpose-built tool fits better. For that path, compare Vanna 2.0 for text-to-SQL on Postgres and Wren AI for generative BI, both of which layer guardrails and modeling that raw DBHub does not. DBHub wins when you want flexibility and a standard protocol; the dedicated tools win when you want an opinionated, end-to-end experience.
Conclusion and Next Steps
The DBHub MCP server turns any MCP-capable AI client into a schema-aware database companion in a few minutes, across Postgres, MySQL, SQL Server, MariaDB, and SQLite. Start in demo mode to confirm it runs, connect it to Claude Desktop over stdio, and — most importantly — run it --readonly against a scoped database role before it touches anything real.
The single best next action is to point the DBHub MCP server at a read-only replica and ask it your three most common data questions; you will learn quickly where it shines and where it needs context. From there, if you want to understand the protocol powering it more deeply, read the MCP protocol explained, then explore building AI agents with tools and planning to scope what your agent should and should not do.
