Skip to main content
Glama
mcp-tabular

mcp-tabular

by ayushsri

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: DuckDB MCP Server

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.

Inputs: table (required). Returns: result

list_tablesA

List tables currently loaded and their source files.

Inputs: no named parameters. Returns: result

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.

Inputs: path (required), table_name. Returns: result

queryC

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

Inputs: sql (required). Returns: result

sample_rowsB

Return n representative rows from a loaded table.

Inputs: table (required), n. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 5 tools

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables DuckDB database interaction through MCP, supporting SQL queries, table creation, and schema inspection with optional read-only mode.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables read-only SQL querying and exploration of data files (CSV, Parquet, JSON, Excel, etc.) via DuckDB, supporting local paths, globs, URLs, and S3 buckets.
      5
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables interaction with a DuckDB database through MCP tools for executing SQL queries, creating tables, and inspecting schemas. It also supports read-only mode to prevent write operations.
      -