search-excel-mcp

Local MCP server that lets any MCP client (Claude Code, Cursor, Claude Desktop, Cline, …) query complex Excel files (heavy merged cells, large size, multi-language text including CJK) via SQL and substring search — no API keys, no embeddings, no GPU.

Built with FastMCP + DuckDB + openpyxl + pyarrow.

Why this exists

Documentation-style Excel files (external design docs, report specs, requirements sheets) typically have thousands of merged cells per sheet, 20–100 MB per file, and multi-language text where most FTS tokenizers fail.

Standard RAG (embeddings + vector store) needs an LLM or embedding model that you can't always run locally. Your MCP client is the reasoning layer; this server just gives it accurate structured access to cells via DuckDB.

Install

pip install search-excel-mcp
# or run without install:
uvx search-excel-mcp

Configure your MCP client

Add to the client's MCP config file. Common locations:

Config entry (same JSON shape for all):

{
  "mcpServers": {
    "search-excel": {
      "command": "uvx",
      "args": ["search-excel-mcp"],
      "env": {
        "SEARCH_EXCEL_DATA_DIR": "/absolute/path/to/your/excel/folder"
      }
    }
  }
}

Only SEARCH_EXCEL_DATA_DIR is required. The DuckDB cache is placed under your OS-standard app data folder (e.g. ~/Library/Application Support/search-excel-mcp/data.duckdb on macOS) — override with SEARCH_EXCEL_DB if you want it elsewhere.

Restart your MCP client → the search-excel server appears.

Use

Drop .xlsx files into your data folder, then ask your agent:

"ingest all the files in the data folder" "find rows that mention '保存ボタン' in any file" "list all sheets in report-2024.xlsx" "show me sheet 5"

The agent routes to the right MCP tool. DuckDB is built incrementally — already-ingested files are skipped unless you re-ingest with reset=true.

CLI (optional)

The same package installs CLI tools for batch use:

# Ingest everything under $SEARCH_EXCEL_DATA_DIR
search-excel-ingest

# Ingest a single file or folder
search-excel-ingest --input /path/to/file.xlsx
search-excel-ingest --input /path/to/folder

# Filter / reset
search-excel-ingest --only "report"
search-excel-ingest --reset

# Validate ingest accuracy (samples random cells against the source xlsx)
search-excel-validate --samples 20

Environment variables

<OS user data dir> resolves per platform via platformdirs:

• macOS: ~/Library/Application Support/search-excel-mcp/
• Linux: ~/.local/share/search-excel-mcp/ (or $XDG_DATA_HOME)
• Windows: %LOCALAPPDATA%\search-excel-mcp\

MCP tools

Accuracy notes

• No LLM in the pipeline → deterministic.
• Cell formatting (font color, bold, fill) is not extracted — only text values. Files that mark changes with red font lose that signal here.
• Read-only MCP for queries; ingest tools mutate DuckDB only.
• search-excel-validate samples cells from the source xlsx and checks them against the DB.
• search_text uses ILIKE (substring) instead of DuckDB FTS so CJK works reliably.

License

MIT