How do I use mcp-tabular?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-tabular load sales.csv and show total revenue by region" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-tabular

by ayushsri

Overview Schema Related Servers Score Discussions

Python

Local

mcp-tabular

An MCP server that gives any LLM agent SQL over CSV and Excel files. DuckDB-powered, read-only, zero configuration.

Why

Embedding spreadsheets into a vector store gives agents mushy answers; tables chunk badly. The pattern that works in production is SQL-over-file: load the table into an analytical engine and let the agent query it. mcp-tabular packages that pattern as a standard MCP server, so it works with Claude Desktop, Claude Code, or any MCP client.

Agent ──MCP──▶ mcp-tabular ──▶ DuckDB (in-memory, read-only)
                  tools: load_file · list_tables · describe_table · query · sample_rows

Related MCP server: sqlite-mcp-local

Install & run

pip install -e .
mcp-tabular            # stdio transport

Claude Desktop config:

{
  "mcpServers": {
    "tabular": { "command": "mcp-tabular" }
  }
}

Tools

Tool	Description
`load_file(path, table_name?)`	Load a CSV/XLSX file into an in-memory table. Returns schema + row count.
`list_tables()`	Tables currently loaded.
`describe_table(table)`	Columns, types, null counts, min/max — enough for the agent to write correct SQL.
`query(sql)`	Read-only SELECT. Results capped and returned as markdown.
`sample_rows(table, n)`	Quick peek at representative rows.

Safety

Read-only: statements other than SELECT/WITH are rejected before execution.
Path allow-listing: set MCP_TABULAR_ROOT to restrict which directory files may be loaded from.
Bounded output: result sets are truncated (default 200 rows) so a bad query can't blow up the agent's context window.

Example session

> load_file("sales_q3.csv")
loaded table 'sales_q3' (8,412 rows). Columns: region VARCHAR, sku VARCHAR, units BIGINT, revenue DOUBLE

> query("SELECT region, SUM(revenue) r FROM sales_q3 GROUP BY 1 ORDER BY r DESC LIMIT 3")
| region | r        |
|--------|----------|
| South  | 412,050  |
| West   | 371,200  |
| East   | 298,700  |

Design notes

Built after shipping enterprise agents where tabular Q&A over uploaded files was the highest-volume use case. Schema + sample injection (via describe_table/sample_rows) is what makes agents write correct SQL on the first try.

License

MIT

Available Tools

5 tools

describe_tableB

Column names, types, null counts, and min/max — enough to write correct SQL.

ParametersJSON Schema

Name	Required	Description	Default
`table`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description does not disclose behavioral traits such as read-only nature, authentication needs, side effects, or caching behavior, which are critical for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at one sentence and front-loads the main output details. However, it could be more structured with usage notes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool with one parameter and an output schema, the description provides the core purpose but misses usage guidance and behavioral details, making it adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'table' lacks any description or context in the tool description. With 0% schema description coverage, the description should clarify the parameter's meaning, but it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns column names, types, null counts, and min/max, which distinguishes it from sibling tools like sample_rows or query. The purpose of enabling correct SQL writing is explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when schema info is needed for SQL, but no explicit guidance on when not to use it or alternatives among siblings are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesA

List tables currently loaded and their source files.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It does not state whether the operation is read-only, requires permissions, or has side effects. While 'List' implies a read, the lack of explicit safety information is insufficient for robust agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It front-loads the main action ('List tables') and adds the key detail ('source files'). Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and an existing output schema, the description is adequate but lacks usage context and behavioral clarity. It could mention that this is the entry point for exploring loaded data, but the minimal info is sufficient for a simple listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is 100% (vacuously). The description does not need to add parameter meaning beyond the schema. Baseline for 0 parameters is 4, and this is met.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'List' and the resource 'tables currently loaded and their source files'. It implicitly distinguishes from sibling tools like 'describe_table' (which targets a specific table) and 'load_file' (which loads new data).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus siblings. It does not mention context such as 'use to get an overview before querying' or 'prerequisites'. The description is minimal and leaves usage assumptions implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

load_fileA

Load a CSV or Excel file into an in-memory table for SQL querying.

Args: path: path to a .csv, .tsv, .xlsx, or .xls file. table_name: optional; defaults to the file stem.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`table_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions 'in-memory' indicating memory usage and supported file types, but does not disclose potential side effects, limits, or error handling. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the main purpose. The Args section is clear and concise. One sentence less would still be acceptable, but current form is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (so return values not needed), the description covers file types, purpose, and parameters. It lacks details on error cases or large file handling but is sufficient for a straightforward loading tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds valuable meaning: path specifies supported file extensions, table_name explains optional behavior and default. Both parameters are well explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Load' and the resource 'CSV or Excel file', with a specific outcome 'into an in-memory table for SQL querying'. This distinctly differentiates it from siblings that query or describe existing tables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage before querying but lacks explicit when-to-use, when-not-to-use, or alternative guidance. Minimal guidance, but not misleading.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryC

Run a read-only SELECT/WITH query. Results are capped at MAX_ROWS.

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses two key behaviors: read-only (non-destructive) and result cap at MAX_ROWS. However, lacks details on error handling, permission requirements, or other side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and key constraints. Very concise, though could add more detail without being wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, one parameter with no description, and sibling tools, the description leaves gaps. Missing parameter explanation, usage context, and full behavioral specification. Output schema exists but doesn't compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and description does not add any information about the 'sql' parameter beyond its name. No examples, syntax hints, or constraints provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Run a read-only SELECT/WITH query', specifying verb and resource. It distinguishes from siblings like describe_table and list_tables by indicating this is for arbitrary queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not mention when not to use (e.g., for modifications) or suggest alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sample_rowsB

Return n representative rows from a loaded table.

ParametersJSON Schema

Name	Required	Description	Default
`n`	No
`table`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It fails to specify the sampling method (random, deterministic?), idempotency, error handling for unloaded tables, or side effects. The brief description leaves significant ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no unnecessary words, but it sacrifices essential details for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and low schema coverage, the description is inadequate for a 2-parameter tool that has an output schema. It omits prerequisites, sampling method, and parameter nuances.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It does not explain parameters: 'n' is described as 'representative rows' without specifying behavior (e.g., max, exact count), and 'table' lacks context about uniqueness or loading status.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'n representative rows from a loaded table', distinguishing it from siblings like describe_table (schema) or query (SQL).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the table must be loaded first but does not explicitly state when to use this over alternatives like query for filtered sampling, nor when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0Jul 12, 2026
- First observeddescribe_table
- First observedlist_tables
- First observedload_file
- First observedquery
- First observedsample_rows

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Disambiguation5/5

Each tool has a clear, distinct purpose: describing schema, listing tables, loading files, running queries, and sampling rows. No overlap in functionality.

Naming Consistency4/5

Most tool names follow a consistent verb_noun pattern (describe_table, list_tables, load_file, sample_rows). 'query' is a single verb but is a common and clear exception that doesn't cause confusion.

Tool Count5/5

With 5 tools covering loading, listing, describing, querying, and sampling, the count is well-suited for a focused tabular data server. No unnecessary or missing tools.

Completeness4/5

The tool set covers the core workflow for read-only SQL querying on loaded tables. Minor gaps like table removal or export exist but are not essential for the stated purpose.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

stagenth · 数据工具箱 A
com.stagenth
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Databases Data Platforms File Systems
62
ContextfloOAuth
com.contextflo
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Databases Security
1
Dataassist-IOOAuth
io.github.DataAssistIO
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search Databases
2
Algenta MCP Server C
io.github.thyn-ai
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Data Platforms Search RAG Systems
1402

Related MCP Servers

mcp-server-duckdb
Databases Developer Tools
fastmcp-me
A
license
A
quality
C
maintenance
Enables DuckDB database interaction through MCP, supporting SQL queries, table creation, and schema inspection with optional read-only mode.
Updated a year ago (2025-10-06 13:08 UTC)
1
MIT
sqlite-mcp-local
Ajaytechgenius
F
license
Not graded
quality
B
maintenance
Enables read-only querying of a local SQLite database via MCP, with tools to list tables, retrieve schema, and execute SELECT/WITH/EXPLAIN queries.
Updated a month ago (2026-07-22 17:30 UTC)
-
duckcoop
Databases File Systems
minsc-of-secrets
A
license
Not graded
quality
B
maintenance
MCP server for sandboxed, read-only SQL queries on CSV/Parquet/JSON files via DuckDB, limited to a specified directory.
Updated a month ago (2026-07-27 14:03 UTC)
1
MIT
DuckDB MCP Server
Databases
poovenp
F
license
Not graded
quality
C
maintenance
Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
Updated a month ago (2026-08-07 06:37 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ayushsri/mcp-tabular'

If you have feedback or need assistance with the MCP directory API, please join our Discord server