# Excel Parser > XLSX parser for LLMs, RAG, LangChain, LangGraph, CrewAI, Claude, MCP โ€” turns Excel (.xlsx) into citation-ready JSON with formulas, charts, dependency graphs, and token-counted chunks. Open-source Python library (MIT). - **Type:** MCP server - **Install:** `agentstack add mcp-knowledgestack-excel-parser` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [knowledgestack](https://agentstack.voostack.com/s/knowledgestack) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [knowledgestack](https://github.com/knowledgestack) - **Source:** https://github.com/knowledgestack/excel-parser - **Website:** https://knowledgestack.github.io/excel-parser/ ## Install ```sh agentstack add mcp-knowledgestack-excel-parser ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ๐Ÿ“Š Make XLSX LLM Ready ๐Ÿค– ks-xlsx-parser โ€” the open-source Python library that parses Excel (.xlsx) files into citation-ready JSON for LLMs, RAG pipelines, and AI agents (LangChain, LangGraph, CrewAI, OpenAI Agents SDK, Claude, MCP). > [!TIP] > **`.xlsx` โ†’ structured, typed, citation-ready JSON that an LLM can actually reason about.** > Cells, formulas, merged regions, tables, charts, conditional formatting, > dependency graphs, and RAG-ready chunks โ€” deterministic, fully tested, MIT. Raw workbook on the left (financial_model.xlsx) โ†’ parser output on the right: 4 chunks, each tied back to an exact sheet!range, ready to cite in an LLM response. Spreadsheets are still the #1 unstructured data source in the enterprise. Feeding a `.xlsx` directly to an LLM loses structure (rows, formulas, merges), loses provenance (which cell said what), and blows through context windows. `ks-xlsx-parser` turns an Excel workbook into a token-counted, source-addressable graph that drops straight into [LangChain](https://www.langchain.com/), [LangGraph](https://langchain-ai.github.io/langgraph/), [CrewAI](https://www.crewai.com/), the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), or any [MCP](https://modelcontextprotocol.io/)-aware client (Claude Desktop, Cursor, Windsurf, Zed, โ€ฆ).       --- ## ๐Ÿ Benchmark โ€” ks-xlsx-parser vs Docling on SpreadsheetBench Apples-to-apples on [SpreadsheetBench v0.1](https://github.com/RUCKBReasoning/SpreadsheetBench): 912 real-world task instances curated from ExcelHome / Mr.Excel / r/excel. For each instance we parse the input `.xlsx`, embed every chunk with `BAAI/bge-small-en-v1.5`, then check whether the chunk containing the ground-truth answer is in the top-k by similarity to the question. Metric ๐ŸŸข ks-xlsx-parser โšช Docling 2.93 ฮ” ๐Ÿ“Š Parse success5,458-file corpus 5,461 ok ยท 3 timeouts ยท 0 errors not run at scale โ€” ๐ŸŽฏ Recall@1text-match ๐ŸŽฏ Recall@3text-match ๐ŸŽฏ Recall@5text-match ๐Ÿ“ Geometric Recall@5chunk's sheet!A1:Z99 overlaps the ground-truth range โšก Mean parse timeper file ๐Ÿงฑ Parser errorsacross 912 instances โ€” ### ๐Ÿ’ก What the numbers mean - **`ks-xlsx-parser` ties at recall@1 and wins recall@3 (+2.7 pp) and recall@5 (+1.8 pp).** Text-match recall is parser-agnostic โ€” it asks whether *any* parser surfaced a chunk containing the answer string, after normalising commas, percent signs, ISO dates, and booleans on both sides. - **`ks-xlsx-parser` wins citation-grade (geometric) recall outright (0.369 vs 0.000).** Docling produces markdown without per-chunk `sheet!range` anchors, so it can't render a citation that points at the exact source cells. This is the difference between "the answer is somewhere in the workbook" and "the answer is in `Revenue!C7`." - **`Marker` is excluded by design.** Its xlsx โ†’ HTML โ†’ PDF โ†’ layout-recognition pipeline clocks >30 min per workbook on CPU. The benchmark framework supports adding a Marker adapter when GPU is available โ€” see [`tests/benchmarks/adapters/docling_adapter.py`](tests/benchmarks/adapters/docling_adapter.py) as a template. ### ๐Ÿ” Reproduce ```bash make corpus-download # one-time, ~100 MB; gitignored under data/corpora/ make bench # robustness + retrieval, ~50 min on M-series CPU open tests/benchmarks/reports/COMPARISON.md ``` Full methodology, capability matrix, error breakdown, and caveats live in [`tests/benchmarks/reports/COMPARISON.md`](tests/benchmarks/reports/COMPARISON.md). Adapter design notes in [`tests/benchmarks/README.md`](tests/benchmarks/README.md). --- ## โœจ What you get, at a glance ๐ŸงพTyped cell graphvalues, formulas, styles, coords ๐ŸงญCitation URIsfile.xlsx#Sheet!A1:F18 ๐ŸงฎDependency graphupstream ยท downstream ยท cycles ๐ŸงฉRAG-ready chunksHTML + text + token count ๐Ÿ“ŠAll 7 chart typesbar ยท line ยท pie ยท scatter ยท area ยท radar ยท bubble ๐ŸŽจConditional formattingevery Excel rule type ๐Ÿ“‹Tables & mergesListObjects + master/slave ๐Ÿ”Safe by defaultno macros ยท no external links ยท ZIP-bomb guard โšกFast1054 workbooks / 70s in CI ๐ŸงฌDeterministicxxhash64 content addressing ๐ŸงฐFramework-agnosticLangChain ยท LangGraph ยท CrewAI ยท MCP ๐Ÿ“œMIT licenseduse it, fork it, ship it --- ## โญ If this helps you This project is free, open source (MIT), and part of the [**Knowledge Stack**](https://github.com/knowledgestack) ecosystem โ€” *document intelligence for agents*. Stars, contributions, and honest feedback are all first-class ways to keep the lights on. **Jump into the community:** - ๐Ÿ’ฌ **[Discord](https://discord.gg/4uaGhJcx)** โ€” real-time help, roadmap conversations, show off what you're building. Drop in, say hi. - ๐Ÿ—ฃ [GitHub Discussions](https://github.com/knowledgestack/ks-xlsx-parser/discussions) โ€” async Q&A, RFCs, and long-form ideas. - ๐Ÿž [Issues](https://github.com/knowledgestack/ks-xlsx-parser/issues/new/choose) โ€” report a bug, request a feature, or file a parser edge case. - ๐ŸŽฏ [Show & Tell](https://github.com/knowledgestack/ks-xlsx-parser/discussions/new?category=show-and-tell) โ€” tell us about your production use. - ๐Ÿ” [Security](https://github.com/knowledgestack/ks-xlsx-parser/security/advisories/new) โ€” private vulnerability disclosure. - ๐Ÿ™Œ [Contribute](CONTRIBUTING.md) โ€” every PR is reviewed; `good-first-issue` labels live on Issues. - ๐Ÿงฐ [Knowledge Stack org](https://github.com/knowledgestack) โ€” see the rest of the ecosystem (ks-cookbook, ks-xlsx-parser, more on the way). Not sure where to start? Run `make bench-robust` on SpreadsheetBench, find a file that breaks, open a [Parser edge case](https://github.com/knowledgestack/ks-xlsx-parser/issues/new?template=parser_edge_case.yml). That's the fastest path to a merged PR. --- ## ๐Ÿš€ 30-second demo ```bash pip install ks-xlsx-parser ``` ```python from ks_xlsx_parser import parse_workbook result = parse_workbook(path="q4_forecast.xlsx") # LLM-ready chunks with citation URIs for chunk in result.chunks: print(chunk.source_uri) # q4_forecast.xlsx#Revenue!A1:F18 print(chunk.token_count) # 412 print(chunk.render_text[:200]) # Pipe-delimited Markdown-ish text print(chunk.render_html[:200]) # HTML with proper colspan/rowspan # Or dump the whole workbook graph import json json.dump(result.to_json(), open("workbook.json", "w"), default=str) ``` That's it. Every chunk has: - `source_uri` โ€” cite back to exact cells - `render_text` / `render_html` โ€” LLM-consumable bodies - `token_count` โ€” cap your context window properly - `dependency_summary` โ€” upstream/downstream formulas - content hash โ€” dedupe across versions --- ## ๐Ÿ—บ๏ธ Table of Contents - [๐Ÿ Benchmark โ€” vs Docling on SpreadsheetBench](#-benchmark--ks-xlsx-parser-vs-docling-on-spreadsheetbench) - [๐Ÿค” Why a dedicated XLSX parser for LLMs?](#-why-a-dedicated-xlsx-parser-for-llms) - [๐Ÿ—๏ธ Architecture](#๏ธ-architecture) - [๐Ÿ“ฆ Installation](#-installation) - [๐Ÿ“š Documentation](#-documentation) - [โš”๏ธ How it compares](#๏ธ-how-it-compares) - [๐ŸŽฏ Who this is for](#-who-this-is-for) - [๐Ÿ“Š Benchmarks](#-benchmarks) - [๐Ÿšง Limitations](#-limitations) - [๐Ÿงฐ Knowledge Stack ecosystem](#-knowledge-stack-ecosystem) - [๐Ÿ“ก Stay in touch](#-stay-in-touch) - [๐Ÿ™Œ Contributing](#-contributing) - [โ“ FAQ](#-faq) - [๐Ÿ“œ License](#-license) --- ## ๐Ÿค” Why a dedicated XLSX parser for LLMs? Most Excel libraries answer one of two questions well: *"read a rectangle of values"* (pandas, openpyxl) or *"run Excel headless"* (xlwings, LibreOffice). `ks-xlsx-parser` answers a third one: **"give me a structured, inspectable, loss-minimising graph that an LLM or auditor can reason about."** | Output | Why an LLM cares | |--------|------------------| | Typed cell graph (values, formulas, styles, coordinates) | Round-trips to JSON/DB/vector store without losing formulas or data types | | Formula AST + directed dependency graph | Answer "what drives Q4 revenue?" via upstream traversal | | Detected tables, merged regions, layout blocks | Multi-table sheets no longer collapse into one giant CSV | | Chart extractions (bar / line / pie / scatter / area / radar / bubble) | Text summaries the model can read | | Token-counted render chunks (HTML + pipe-text) | Plug straight into an embedding pipeline without blowing context | | Citation-ready source URIs (`sheet!A1:B10`) | The LLM can cite the exact cell it's talking about | | Deterministic content hashes (xxhash64) | Dedupe across versions, detect change between uploads | Everything is deterministic, everything is tested on a 1054-workbook stress corpus, and everything is open source. --- ## ๐Ÿ—๏ธ Architecture The pipeline runs **8 deterministic stages**: parse โ†’ analyse โ†’ annotate โ†’ segment โ†’ render โ†’ serialise โ†’ verify โ†’ compare/export. Full diagram, stage-by-stage breakdown, and module map in [**docs/wiki/Architecture.md**](docs/wiki/Architecture.md). Stage internals in [**Pipeline Internals**](docs/wiki/Pipeline-Internals.md). > [!NOTE] > The importable module is `xlsx_parser`; `ks_xlsx_parser` is a re-export > matching the PyPI package name. The package is fully type-annotated > (`py.typed` is shipped). --- ## ๐Ÿ“ฆ Installation Requires Python 3.10+. ```bash pip install ks-xlsx-parser # core library pip install "ks-xlsx-parser[api]" # + FastAPI web server pip install "ks-xlsx-parser[dev]" # + test tooling ``` From source: ```bash git clone https://github.com/knowledgestack/ks-xlsx-parser.git cd ks-xlsx-parser make install # pip install -e ".[dev,api]" make test # default suite make corpus-download # fetch SpreadsheetBench (5,458 real-world xlsx) make bench-robust # parse-success + structural counts vs Docling make bench-retrieval # retrieval recall@k vs Docling ``` Runtime deps: `openpyxl`, `pydantic`, `lxml`, `xxhash`, `tiktoken`. --- ## ๐Ÿ“š Documentation All implementation detail lives under [`docs/wiki/`](docs/wiki/) (mirrored to the [GitHub Wiki](https://github.com/knowledgestack/ks-xlsx-parser/wiki) on each release) so this README stays scannable: - ๐Ÿš€ [**Quick Start**](docs/wiki/Quick-Start.md) โ€” parse, iterate chunks, walk the dep graph, serialise, parse from bytes. Five short snippets, ~90 % of real usage. - ๐Ÿ“– [**API Reference**](docs/wiki/API-Reference.md) โ€” full signatures for `parse_workbook`, `compare_workbooks`, `export_importer`, `StageVerifier`. - ๐ŸŒ [**Web API**](docs/wiki/Web-API.md) โ€” the bundled FastAPI server, Python + TypeScript clients, deployment notes. - ๐Ÿ“ฆ [**Data Models**](docs/wiki/Data-Models.md) โ€” every Pydantic DTO field by field. - ๐Ÿ›  [**Pipeline Internals**](docs/wiki/Pipeline-Internals.md) โ€” where to hook in if you want to extend the parser. - ๐Ÿ“œ [**Workbook Graph Spec**](docs/WORKBOOK_GRAPH_SPEC.md) โ€” canonical schema for the output. - ๐Ÿ› [**Known Issues**](docs/PARSER_KNOWN_ISSUES.md) โ€” documented edge cases. - ๐Ÿ“ [**CHANGELOG**](CHANGELOG.md) โ€” release history. --- ## โš”๏ธ How it compares This is the **structural** capability matrix. For head-to-head retrieval numbers (recall@k, geometric, latency) on a 912-instance real-world corpus, see [๐Ÿ Benchmark โ€” ks-xlsx-parser vs Docling on SpreadsheetBench](#-benchmark--ks-xlsx-parser-vs-docling-on-spreadsheetbench) up top. | | pandas / openpyxl | Docling | `ks-xlsx-parser` | |---|:---:|:---:|:---:| | Reads values | โœ… | โœ… | โœ… | | Keeps **formulas** | โš ๏ธ raw string | โŒ | โœ… parsed + dependency graph | | Preserves **merges** | โš ๏ธ coords only | โš ๏ธ partial | โœ… master/slave with colspan/rowspan | | Extracts **charts** | โŒ | โŒ | โœ… all 7 chart types + text summary | | **Conditional formatting** | โŒ | โŒ | โœ… cell/color-scale/icon/data-bar/formula | | **Data validation** (dropdowns) | โŒ | โŒ | โœ… all types incl. cross-sheet lists | | **Multi-table** sheet layout | โŒ | โš ๏ธ | โœ… adaptive-gap segmentation | | Per-chunk **source URI** (citation) | โŒ | โš ๏ธ | โœ… `file.xlsx#Sheet!A1:F18` | | **Token counts** per chunk | โŒ | โŒ | โœ… via `tiktoken` | | **Dependency graph** traversal | โŒ | โŒ | โœ… upstream / downstream, cycle detection | | Deterministic **content hashes** | โŒ | โŒ | โœ… xxhash64 per cell / block / chunk | | Streaming `.xlsx` > 100 MB | โš ๏ธ | โŒ | โœ… (chunked parse) | Most tools give you a dataframe. `ks-xlsx-parser` gives you a **graph an LLM can cite**. --- > Looking for a tiny, edge-runtime I/O library with write support? See > [**`hucre`**](https://github.com/productdevbook/hucre) by > [**@productdevbook**](https://github.com/productdevbook). For an unbiased > head-to-head on the SpreadsheetBench corpus โ€” perf numbers, > extraction-count parity, where each side wins โ€” see the wiki: > [**`ks-xlsx-parser` vs `hucre`**](docs/wiki/Benchmark-vs-hucre.md). --- ## ๐ŸŽฏ Who this is for Teams shipping agents, RAG pipelines, or auditing tools that ingest Excel. ๐ŸฆBanking & FinanceKPI extraction, formula lineage, regulator-ready citations โš–๏ธLegal & Contractsschedules, fee tables, covenant matrices without flattening merges ๐ŸฅHealthcare & Insurancenormalise claims, pricing, and actuarial sheets into auditable JSON ๐Ÿ—๏ธReal Estate & Constructionquantity takeoffs and cost models that still live in XLSX ๐Ÿ“ˆSales Ops / HR / Engineering"source of truth is a spreadsheet" โ†’ structured events, in minutes > [!IMPORTANT] > **Not a fit** if you need to *execute* Excel (recalculate, run VBA, pivot-refresh). > Use xlwings or a headless Excel for that. `ks-xlsx-parser` reads; it doesn't run. --- ## ๐Ÿ“Š Benchmarks We benchmark against **SpreadsheetBench v0.1** โ€” 912 instruction ร— xlsx tasks (5,458 unique workbooks) covering financial models, project trackers, HR records, scientific data, and a long tail of small business spreadsheets. | Benchmark | What it measures | Cost | |---|---|---| | `make bench-robust` | Parse-success rate + structural counts vs Docling | ~20 min | | `make bench-retrieval` | Top-k retrieval recall + table fragmentation rate vs Docling | ~40 min | Headline numbers and methodology live in [`tests/benchmarks/reports/COMPARISON.md`](tests/benchmarks/reports/COMPARISON.md). The corpus is downloaded on demand (`make corpus-download`) and gitignored โ€” nothing is committed to the repo. --- ## ๐Ÿšง Limitations - **`.xls` not supported** โ€” only `.xlsx` and `.xlsm` (OOXML). Convert legacy files externally. - **Pivot tables** โ€” detected but not fully parsed. - **Sparklines** โ€” not extracted. - **VBA macros** โ€” flagged but never executed or analysed. - **External links** โ€” recorded but not resolved. - **Threaded comments** โ€” only legacy comments are supported (openpyxl limitation). - **Embedded OLE objects** โ€” detected but not extracted. - **Locale-dependent number formats** โ€” not interpreted. Full list in [`docs/PARSER_KNOWN_ISSUES.md`](docs/PARSER_KNOWN_ISSUES.md). --- ## ๐Ÿงฐ Knowledge Stack ecosystem `ks-xlsx-parser` is one piece of the [**Knowledge Stack**](https://github.com/knowledgestack) open-source family โ€” *document intelligence for agents*, built so that engineering teams can focus on agents and we handle the messy parts of enterprise data. | Repo | What it does | |------|--------------| | [**ks-cookbook**](https://github.com/knowledgestack/ks-cookbook) | 32 production-style flagship agents + recipes for LangChain, LangGraph, CrewAI, Temporal, the OpenAI Agents SDK, and any [MCP](https://modelcontextprotocol.io/) client. | | [**ks-xlsx-parser**](https://github.com/knowledgestack/ks-xlsx-parser) (this repo) | Turn `.xlsx` into LLM-ready JSON with citations and dependency graphs. | | [@knowledgestack](https://github.com/knowledgestack) | Follow the org for upcoming repos โ€” parsers, extractors, and MCP servers for PDF, DOCX, PPTX, HTML, and more. | Building on top of the stack? Tell us about it in [Show & Tell](https://github.com/knowledgestack/ks-xlsx-parser/discussions/new?category=sh โ€ฆ ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [knowledgestack](https://github.com/knowledgestack) - **Source:** [knowledgestack/excel-parser](https://github.com/knowledgestack/excel-parser) - **License:** MIT - **Homepage:** https://knowledgestack.github.io/excel-parser/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-knowledgestack-excel-parser - Seller: https://agentstack.voostack.com/s/knowledgestack - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.