text-spreadsheet
================

An MCP (Model Context Protocol) server that lets AI agents read Excel
(XLSX), ODS, CSV, JSON, SQLite, Parquet, Arrow and MTSV files, or a whole
folder of them, as plain text. The agent calls one tool, `read`, with the
pathname of a file or folder on your machine, and every sheet comes back as
Multi-Sheet Tab-Separated Values (MTSV): a tab separates fields, a line
break separates records, and a form feed separates sheets.

Why It Is Useful
----------------

A language model reads text, so a binary Excel workbook is closed to
it unless pandas or openpyxl is in the loop. text-spreadsheet converts the
whole file, every sheet, in one call, and lets the agent choose sheets,
records and fields and filter them, so it reads a spreadsheet the way it
reads any other text file. Nothing outside your machine is contacted.

Get Started
-----------

* Install: `pipx install text-spreadsheet`
* Connect it to your AI agent: tell its MCP host, such as Claude Code, Codex or Cursor, to launch `text-spreadsheet` with no arguments, once
* Use it: the agent calls `read("/home/me/book.xlsx")`
* The tool, its selections and filters, and what it keeps: [python/README.md](python/README.md)

Details
-------

* Specification: [MTSV, an IETF Internet-Draft](https://github.com/demos-ra/mtsv-spec), and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
* Requirements: Python 3.11 or later; [mtsv](https://github.com/demos-ra/mtsv), which does every conversion, installed with it
* Version: the version field of [python/pyproject.toml](python/pyproject.toml); released on [PyPI](https://pypi.org/project/text-spreadsheet/) and in the [MCP registry](https://registry.modelcontextprotocol.io) as `io.github.demos-ra/text-spreadsheet`; versions follow [Semantic Versioning](https://semver.org)
* Layout: [server.json](server.json), the entry that lists this server in the MCP registry; [python/](python/README.md), the Python implementation
* License: [MIT](LICENSE)

Get Help
--------

* Issues: [text-spreadsheet issue tracker](https://github.com/demos-ra/text-spreadsheet/issues)
* Security: [SECURITY.md](SECURITY.md)
* Maintainer: Demos Ra
* More: [all MTSV tools by Demos Ra](https://github.com/demos-ra)