Connect MariaDB to Claude with MCP

MCP · MariaDB to Claude

Ask Claude about your MariaDB database, in plain English

Connect claude.ai, Claude Desktop, ChatGPT, Cursor or any MCP client to Query Streams once. Your AI client asks; the Agent that already sits with your MariaDB database, its partner inside your network, does the heavy lifting: it runs the SQL read-only, and on paid plans it also sizes, profiles and holds results so follow-ups need no second query. No database password ever reaches the AI. About ten minutes, and the Free plan covers it.

About 10 minutes Claude, ChatGPT, Cursor + 11 more clients Data stays on your network Read-only, always

What you’ll end up with

A Claude that can answer questions about your MariaDB database with live, read-only queries, explain what the columns mean, and follow up when you ask for more — without ever seeing a database login, and without a firewall change: the Agent already inside your network runs the SQL and sends back only the rows. Once the Agent is in place, connecting Claude takes about 90 seconds if you are comfortable with a settings screen. Like this:

Claude ChatGPT Cursor Claude Code VS Code Windsurf Gemini CLI JetBrains Codex+5 moreRead-only

What is in customers in my MariaDB database? Show me a few rows and tell me what each column means.

qs_get_table_schema qs_run_query schema_intelligence

I looked at the table structure first, then ran a read-only query through your Agent. Here are three of the customers rows:

customer_id	name	city
1042	Northwind Traders	Seattle
1057	Alpine Outfitters	Denver
1063	Harbour Foods	Halifax

customer_id identifies the row. name and city are described in your Semantic Intelligence model, so I can filter on them by name.

Which three city values brought in the most revenue this quarter, and how does that compare with last quarter? Anything I should look into?

qs_get_relationships qs_run_query qs_run_query

I joined customers to orders on the relationship Semantic Intelligence found, then ran one aggregate for each quarter. Both queries were read-only and returned 3 rows each:

city	This quarter	Last quarter	Change
Denver	184,200	133,900	+38%
Seattle	171,650	168,400	+2%
Halifax	96,300	129,700	−26%

Denver is the story: revenue up 38% on almost the same number of customers, so average order value rose. Halifax fell 26%, and the drop is two customers who ordered every month last quarter and not at all this quarter — worth a call before month end. Seattle is flat. Want the two Halifax accounts by name?

SELECT only, checked by the Agent logged on the MCP Activity tab 9 rows returned across 3 queries Same connection in 14 MCP clients

Rather not wire up an AI client at all? On the Business plan, Nova is the assistant built into Query Streams itself. It uses the same Agent toolset your AI client gets here, plus what an outside client does not: it drafts and validates the SQL against your Semantic Intelligence model, turns the answer into a chart, and saves the result as a query your team can run from Excel, Google Sheets or the REST API — no key, no connector, nothing to install. Use MCP when your people already live in Claude, Cursor or ChatGPT; use Nova when you want the answers inside the Portal.

MariaDB holds your data on a server you or your team run. Claude, on the other hand, lives in a browser or a terminal and knows nothing about it. The usual bridge is pasting a schema into the chat and hoping, or handing an open-source MCP server your MariaDB password. Query Streams does it differently: the Agent that already sits with your MariaDB database runs the SQL Claude writes, read-only, and the MCP server in between checks who is asking, what they may do and how often. Claude gets answers. It never gets credentials.

What you’ll need

A Query Streams account

MCP is on every plan, including Free. Free allows one key or one connected app, which is all this guide needs. Sign up at my.querystreams.com.

MariaDB connected through the Agent

The Agent installed where your MariaDB database is, with the connection added in Data Agents. Not done yet? Connect MariaDB first; it takes about ten minutes.

MCP switched on for you

Creators, owners and admins have it from the start. Everyone else needs an admin to flip the MCP switch beside their name under Account → Access Control. Until then the MCP page says “MCP is disabled for your account”.

An AI client

Chat apps such as claude.ai, Claude Desktop and ChatGPT connect with no key. Claude Code, Cursor, VS Code and about ten other tools use a key; the Portal’s Connect an AI client guide sets up each one.

Set it up in four steps

1. Open MCP in the portal

   Sign in at my.querystreams.com and open Streams → Live → MCP. The page has four tabs: Connections, Context, Tools and, for admins, Activity. Check the Semantic Intelligence panel on Connections while you are here: it lists your MariaDB connector and whether Semantic Intelligence has run on it. Complete coverage is what lets Claude write correct MariaDB SQL on the first try.

   Open MCP

   Seeing “MCP is disabled for your account”? Your organization has MCP but your user is switched off. An admin turns it on with the MCP switch beside your name under Account → Access Control. Creators, owners and admins are on from the start.

2. Choose how you will connect

   There are two ways in, and they end at the same place:

   Chat apps · no key

   claude.ai, Claude Desktop, ChatGPT

   In claude.ai and Claude Desktop, open the Query Streams listing in Anthropic’s Connectors Directory, click Connect and approve. Adding it by URL, https://mcp.querystreams.com/mcp, is the fallback. In ChatGPT you add Query Streams from the app (developer mode for now) and sign in with Query Streams. Either way a Query Streams page opens: pick the organization and the permissions and click Approve connection. Nothing to copy. The connection appears on the Connections tab and can be revoked there.

   Developer tools · a key

   Claude Code, Cursor, VS Code and friends

   On the MCP page click Connect an AI client. The guide asks How will your AI client connect?: choose Use a key in a config file, pick your tool, then Generate a key for it: a Key name, Read and Run queries ticked, an Expiration (Never, 30 days, 90 days or 1 year). Set it up shows the snippet with the key filled in, and Check the connection waits for the first call.

   Both ways use the same three permissions, which you choose on the consent screen or on the key:

   Read

   List connectors, browse tables and columns, read your saved queries and alert rules. Never returns row data.

   Run queries

   Run read-only SQL and saved queries through your Agent and return the rows. Without it your AI client can describe your data but not answer from it.

   Analyze

   Profile tables, discover relationships and queue a Semantic Intelligence run. It spends Nova AI credits and data allowance, so the consent screen never pre-ticks it.

   Lost the key? It is listed on the Connections tab: Reveal full key shows it again and Copy full key copies it. Revoke it there if a laptop goes missing; every client using it fails on its next call, within about five minutes.

3. Connect Claude

   Pick the recipe for the Claude you use. The server address is the same everywhere: https://mcp.querystreams.com/mcp.

   Claude on the web, Claude Desktop and mobile no key

   1. Open the Query Streams listing in Anthropic’s Connectors Directory and click Connect. In Desktop it then sits under + → Connectors.
   2. Fallback, if your organization hides directory connectors: Settings → Connectors → Add custom connector, name Query Streams, URL https://mcp.querystreams.com/mcp, OAuth fields empty, Add; then in a chat + → Query Streams → Connect.
   3. A Query Streams tab opens. Sign in if asked, pick the organization, review Read and Run queries, optionally Limit to specific connectors, and click Approve connection.
   4. Back in Claude you see “Connected to Query Streams”. The first time Claude uses a tool it asks; choose Always allow.

   If you do add it by hand in Claude Desktop, use Settings → Connectors → Add, not the in-chat Add marketplace option, which expects a git repository. Connectors sync to your Claude account, so the mobile apps and Desktop pick it up automatically. Menu names are Anthropic’s and can move.

   Claude Code key

   One command, with your key from the Connections tab:

   Terminal

   claude mcp add --transport http querystreams https://mcp.querystreams.com/mcp \
     --header "X-MCP-Key: qsmcp_PASTE_YOUR_KEY_HERE"

   That writes the current project’s .mcp.json. Add --scope user to have Query Streams in every project. Run /mcp inside Claude Code to see it connected.

   Cursor key

   Open Cursor Settings → MCP → Add New MCP Server, or edit .cursor/mcp.json at the root of your workspace:

   .cursor/mcp.json

   {
     "mcpServers": {
       "querystreams": {
         "url": "https://mcp.querystreams.com/mcp",
         "headers": {
           "X-MCP-Key": "qsmcp_PASTE_YOUR_KEY_HERE"
         }
       }
     }
   }

   Restart Cursor or run MCP: Restart Servers; a querystreams badge appears in the MCP status bar.

   Using something else? The Portal’s Connect an AI client guide has ready-to-paste recipes for ChatGPT, VS Code, Visual Studio, OpenAI Codex CLI, Gemini CLI, Windsurf, Zed, Cline, Continue.dev and JetBrains AI, plus a Paste & merge tool that drops the querystreams entry into a config file you already have. Any client that speaks MCP over HTTP works: server https://mcp.querystreams.com/mcp, header X-MCP-Key (an Authorization: Bearer header with the same key also works).

4. Ask your first question

   Start with something you already know the answer to, so you can see Claude reach for the right tool. Three that work well with your MariaDB database:

   “What data do I have in my MariaDB database?”

   Claude lists the tables it can see, tells you which have Semantic Intelligence, and asks what you want to look at.

   “Show me ten rows from customers and explain each column.”

   Claude reads the table structure first (Read), then runs one SELECT through your Agent (Run queries) and describes what name and city mean.

   “How many rows does customers have per city? Which city has the most?”

   Claude writes the GROUP BY in MariaDB’s dialect, runs it, and answers in a sentence with a small table. Follow up in the same chat; it keeps the context.

   To confirm the wiring, ask “What Query Streams connectors do I have?”. Claude calls qs_list_connectors, the Portal guide’s Check the connection step says Connected, and the key or app on the Connections tab shows its Last used time within a few seconds.

What Claude can do once connected

Your AI client sees the Query Streams tools; it picks the right one for your question. The Portal’s Tools tab lists all 38 tools and modes with what your plan includes. On every plan, Free included:

The Analytic toolset. On paid plans the Agent does the groundwork where your MariaDB database lives, so your AI client spends its attention on the thinking. Free works as it always has.

The defaults live on the Context tab: text cell limit, schema view, result size, analysis defaults and held results.

Why Semantic Intelligence matters here

Every answer Claude receives is tagged with where the structure came from, and Claude adjusts how much it trusts what it sees.

If a database matters, run Semantic Intelligence on it once from Nova → Intelligence. The Connections tab shows a coverage panel per connector. How Semantic Intelligence works.

What the plans allow

MCP is on every plan, including Free, with no separate fee. What each plan sets is how many keys or connected apps you can hold and how many calls a minute your AI client may make:

A connected app counts as a key. On top of the per-minute figure, any one key may run at most 10 queries a minute. A query runs for up to 60 seconds unless your AI client asks for more, up to five minutes. Your plan also sets how many rows one query returns and, with the Analytic toolset, how long and how large a held result may be; the full MCP guide lists every plan. The rows your AI client receives count against your Data Realm allowance, the same pool your Excel and Sheets queries use, and MCP is measured the same way as your spreadsheet queries. Semantic Intelligence runs started from Claude spend Nova AI credits, exactly as they do from the Portal. See the pricing page for the allowances.

Keeping it safe

Good next moves

• Save the queries you consider canonical in Query Builder. Claude reaches for saved queries first, so “active customers” means what your team says it means.
• Use a Claude Project with Query Streams attached and put your house rules in its instructions: which MariaDB database to use by default, which saved queries are the official definitions.
• Grant Analyze when you want deeper answers. Profiling a column before filtering on it is the difference between guessing a status code and using the right one. It spends Nova AI credits, so it is off until you say so.
• Ask for a chart. claude.ai draws charts from the rows Claude gets back.

When something doesn’t work

Questions people ask

Related guides

• Connect Microsoft SQL Server to Claude with MCP
• Connect PostgreSQL to Claude with MCP
• Connect MySQL to Claude with MCP
• Connect Microsoft Access to Claude with MCP
• Connect Query Streams to Claude via MCP: setup, permissions and troubleshooting
• How to connect MariaDB to Google Sheets
• All MCP guides