Connect a Folder of CSV Files to Claude with MCP

CSV FolderFree planQuery StreamsClaude

CSV Folder → Claude · with Query Streams

With Query Streams, ask Claude about your CSV Folder file in plain English: the Agent already inside your network runs the SQL read-only, and no database password ever reaches the AI. About ten minutes, and the Free plan covers it.

Start free

What you’ll end up with

A Claude that can answer questions about a folder of CSV files with live, read-only queries over the tables the Agent builds from your files, and tell you which file each answer came from — without ever seeing a login or a file path, and without a firewall change: the Agent already inside your network reads the folder 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 · connected to Query Streams Read-only

Which files feed fileset.sales, and how many rows does each one add?

qs_get_table_schema qs_run_query schema_intelligence

Three CSV files feed fileset.sales. The September export is the largest, with just over 18,000 rows.

_source_file	row_count	first_row_id
exports/sales_2026_09.csv	18422	exports/sales_2026_09.csv:0000000
exports/sales_2026_08.csv	17305	exports/sales_2026_08.csv:0000000
exports/sales_2026_07.csv	16988	exports/sales_2026_07.csv:0000000

Want me to total sales by month across all three files?

Which regions grew the most this month against last month, and did anything drop?

qs_run_query qs_run_query

Every CSV is already one table, so I summed amount by region for each month straight from fileset.sales. Two read-only queries:

region	This month	Last month	Change
West	412,300	348,900	+18%
Central	388,120	391,000	−1%
East	201,450	262,800	−23%

West is up on more orders, not bigger ones. East fell 23%, and it is one account: Harbour Foods ordered every week last month and not once this month. Central is flat. Want the East orders by customer?

SELECT only, checked by the Agent logged on the MCP Activity tab 6 rows returned across 3 queries

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.

The CSV Folder card merges every CSV file in a folder into one SQL table that Claude can query, and tags each row with the file it came from. You do not upload files to a chat. You point the Agent at the folder once, it copies the rows into a local cache on its computer, and it keeps the table current as files arrive or change.

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.

The Agent on a computer that can open the folder

Version 2.6.0 or later. The folder can be on that computer or on a file share it can reach. The Agent runs as a service, so type shares as \\server\share\folder, not as a mapped drive letter. On Windows it can sign in to a share with a login you store; on Linux or a Mac, mount the share first (Linux under /mnt or /media, a Mac under /Volumes). New to the Agent? Install it on Windows, macOS or Linux.

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

Claude on the web, Claude Desktop or the Claude mobile apps connect with no key. Claude Code, Cursor, ChatGPT and about ten other tools work too; the Portal has a ready-made recipe for each.

Set it up in four steps

1. Point the Agent at the folder

   In the portal open Data → Data Agents, find the Agent that can open the folder and click its Add connector button. Under the Files & Folders pill click the CSV Folder card. The wizard then walks you through Folders, Check, Settings, Realm and Review:

   Folders

   Type the Root folders, one per line, as paths on the Agent’s computer. Scan subfolders is on, Max depth is 8. Include patterns starts with the right glob for this file type; add Exclude patterns if the folder holds files you do not want. A mapped drive letter shows an amber advisory: the Agent cannot see it, so use the \\server\share path instead.

   Check

   The Agent reads a sample of up to 64 files and shows what it will build. Nothing is created yet. Ready to create means every sampled file fits. An amber banner, “{n} of {m} file(s) will be set aside”, lists files that do not fit with Show which files and why; you can create the connector anyway and fix them later. If the folder mixes layouts, a blue panel offers Switch to one table per layout.

   Settings

   Scan interval (every hour by default, from every 5 minutes to daily) is how often the Agent looks for new, changed and vanished files. Watch folder for changes reacts within seconds on local disks. When a file vanishes is Drop its rows by default.

   Realm, Review

   Pick the Data Realm the rows count against, check the summary and click Create connector. The first scan starts right away; the connector’s Manifest tab shows what it built and any files it set aside.

   • Type a Table name, for example sales. It is required on this card.
   • Include patterns starts as **/*.csv.
   • Pick a Table layout. One pinned layout (default) suits recurring exports that all share one header. One table per layout suits folders people assemble by hand, up to 25 layouts.
   • On Check, the Agent reads a sample and shows the file count, a row estimate and the tables it will build. If the folder mixes layouts, a blue panel says so. Click Switch to one table per layout.
   • An amber banner lists files that will be set aside. Open Show which files and why to see the reason for each.

2. See what tables you get

   Everything sits in the fileset schema. The data table takes the name you type in Table name. Its columns come from the CSV header, plus _source_file and _row_id on every row.

   Table	What it holds
   fileset.sales	With One pinned layout, one table named by your Table name, holding the rows of every matched CSV.
   fileset.orders, fileset.returns	With One table per layout, one table per layout, named after the shared part of the file names. orders_2026_01.csv to orders_2026_03.csv become orders.
   fileset.files	One row per CSV file that is there now, with its path, size and modified time.
   fileset.files_events	The change history, including a drift row for every file that was set aside, with the reason in detail.

   Every folder connector also gives Claude the same bookkeeping tables, all in the fileset schema:

   Table	What it holds
   files	Every file currently in the folder: path, name, extension, size, created and modified times. Ask “what is in this folder?” and Claude reads this.
   files_events	The change history: one row per file that appeared, was modified, vanished, or was set aside (drift), with the time in event_at and the reason in detail.
   directories, volumes	Folder sizes and counts, and the disks or shares the roots live on.
   _source_file, _row_id	Two columns on every data row: which file the row came from, and a stable row id inside that file. Group by _source_file to compare files.

3. Connect Claude

   Open Streams → Live → MCP. 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. Profiling and discovery are free; a Semantic Intelligence run 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.

   Then 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 can check by opening the folder, so you see Claude reach for the right table. Three that work well with a folder of CSV files:

   “Which CSV files are in the folder, and when did each one last change?”

   Claude queries fileset.files (Run queries) and lists each file with size_bytes and modified_utc, newest first.

   “Total the amount column in fileset.sales by month.”

   Claude reads the table schema first to find the real column names (Read), then runs one DuckDB GROUP BY through your Agent (Run queries). You get a small table of monthly totals.

   “Were any CSV files set aside, and why?”

   Claude queries fileset.files_events for drift and refused rows, ordered by event_at (Run queries). You get each file and the reason in detail.

   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.

Reaching a file on a network share

The Agent opens files as a background service, not as you, so a file on another computer needs one extra step. Which step depends on the computer the Agent runs on.

If the test cannot get to the share, look for these words in its result: unreachable means the Agent’s computer got no answer from the server. On Linux or a Mac, not mounted means the share still has to be mounted, and that message includes the exact mount command for your server.

How new, changed and deleted files show up

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 every tool and mode with what your plan includes. Query Streams asks your AI client to read the columns of each table before it queries, so it writes the real names instead of guessing. On every plan, Free included:

The Analytic toolset. On paid plans the Agent does the groundwork where your CSV Folder file 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. What your AI client receives counts against your Data Realm allowance, the same pool your Excel and Sheets queries use: AI-agent (MCP) usage counts every byte delivered to your AI client, results, schema reads and held-result pages alike, before any transport compression your client negotiates, where spreadsheet queries count the compressed result your Network Agent delivers. Semantic Intelligence runs started from your AI client spend Nova AI credits, exactly as they do from the Portal. See the pricing page for the allowances.

Keeping it safe

Good next moves

• Run Semantic Intelligence on the connector so Claude sees descriptions of your own CSV columns, not just the file tables.
• Add a second connector on the same folder if it also holds Parquet or Excel files. One connector reads one file type.
• Read the CSV Folder guide at Combine multiple CSV files into one table for every setting.

When something doesn’t work

Questions people ask

Related guides

• Connect a Folder of Excel Files to Claude with MCP
• Connect a Folder of SQLite Databases to Claude with MCP
• Connect a Folder of Parquet Files to Claude with MCP
• Connect a Folder of JSONL Files to Claude with MCP
• The CSV Folder connector guide
• Connect Query Streams to Claude via MCP: setup, permissions and troubleshooting
• All MCP guides