mcp-server-spreadsheet 0.2.0__tar.gz

mcp_server_spreadsheet-0.2.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run python -c \"\nfrom odf.table import Table\nprint\\(type\\(Table\\)\\)\nprint\\(repr\\(Table\\)\\)\n# check if it's a class or something else\nimport inspect\nprint\\('is class:', inspect.isclass\\(Table\\)\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nfrom odf.table import Table, TableRow, TableCell\n# Create instances to get their qname\nt = Table\\(\\)\ntr = TableRow\\(\\)\ntc = TableCell\\(\\)\nprint\\('Table qname:', t.qname\\)\nprint\\('TableRow qname:', tr.qname\\)\nprint\\('TableCell qname:', tc.qname\\)\nprint\\('type of element:', type\\(t\\)\\)\nprint\\('type name:', type\\(t\\).__name__\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nfrom backends import load_workbook\n\n# --- XLSX ---\nwb = load_workbook\\('examples/example.xlsx'\\)\nprint\\('=== XLSX ==='\\)\nprint\\('Sheets:', wb.sheetnames\\)\nfor ws in wb.worksheets:\n    print\\(f'  {ws.title}: {ws.max_row} rows x {ws.max_column} cols'\\)\n    rows = list\\(ws.iter_rows\\(max_row=3\\)\\)\n    for r in rows:\n        print\\(f'    {r}'\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nfrom backends import load_workbook\n\n# --- CSV free-form ---\nwb = load_workbook\\('examples/example-free-form.csv'\\)\nprint\\('=== CSV free-form ==='\\)\nprint\\('Sheets:', wb.sheetnames\\)\nws = wb.worksheets[0]\nprint\\(f'  {ws.title}: {ws.max_row} rows x {ws.max_column} cols'\\)\nrows = list\\(ws.iter_rows\\(max_row=5\\)\\)\nfor r in rows:\n    print\\(f'    {r}'\\)\n\nprint\\(\\)\n\n# --- CSV table ---\nwb = load_workbook\\('examples/example-table.csv'\\)\nprint\\('=== CSV table ==='\\)\nws = wb.worksheets[0]\nprint\\(f'  {ws.title}: {ws.max_row} rows x {ws.max_column} cols'\\)\nrows = list\\(ws.iter_rows\\(max_row=5\\)\\)\nfor r in rows:\n    print\\(f'    {r}'\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nfrom backends import load_workbook\n\n# --- ODS ---\nwb = load_workbook\\('examples/example.ods'\\)\nprint\\('=== ODS ==='\\)\nprint\\('Sheets:', wb.sheetnames\\)\nfor ws in wb.worksheets:\n    print\\(f'  {ws.title}: {ws.max_row} rows x {ws.max_column} cols'\\)\n    rows = list\\(ws.iter_rows\\(max_row=3\\)\\)\n    for r in rows:\n        print\\(f'    {r}'\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nimport shutil, os, tempfile\n\n# Work on copies to avoid modifying originals\ntmpdir = tempfile.mkdtemp\\(\\)\nfor f in os.listdir\\('examples'\\):\n    shutil.copy2\\(f'examples/{f}', f'{tmpdir}/{f}'\\)\n\n# Import tools\nfrom main import \\(\n    list_workbooks, read_sheet, read_cell, read_range,\n    get_sheet_dimensions, search_sheet, list_sheets,\n    write_cell, append_rows, describe_table, sql_query,\n\\)\n\n# --- list_workbooks ---\nfiles = list_workbooks\\(tmpdir\\)\nprint\\('list_workbooks:', files\\)\nassert len\\(files\\) == 4  # 2 csv + 1 xlsx + 1 ods\n\n# --- XLSX tests ---\nxlsx = f'{tmpdir}/example.xlsx'\nprint\\(\\)\nprint\\('=== XLSX tool tests ==='\\)\nprint\\('list_sheets:', list_sheets\\(xlsx\\)\\)\nprint\\('dimensions \\(Free-form\\):', get_sheet_dimensions\\(xlsx, sheet='Free-form'\\)\\)\nprint\\('read_cell B2:', read_cell\\(xlsx, 'B2', sheet='Free-form'\\)\\)\nprint\\('read_range A1:B3:', read_range\\(xlsx, 'A1:B3', sheet='Free-form'\\)\\)\nprint\\('search:', search_sheet\\(xlsx, 'sql_query', sheet='Table'\\)\\)\n\n# --- CSV tests ---\ncsv_f = f'{tmpdir}/example-table.csv'\nprint\\(\\)\nprint\\('=== CSV tool tests ==='\\)\nprint\\('list_sheets:', list_sheets\\(csv_f\\)\\)\nprint\\('dimensions:', get_sheet_dimensions\\(csv_f\\)\\)\nprint\\('read_cell A1:', read_cell\\(csv_f, 'A1'\\)\\)\nprint\\('read_range A1:C3:', read_range\\(csv_f, 'A1:C3'\\)\\)\nprint\\('search:', search_sheet\\(csv_f, 'sql_query'\\)\\)\n\n# --- ODS tests ---\nods = f'{tmpdir}/example.ods'\nprint\\(\\)\nprint\\('=== ODS tool tests ==='\\)\nprint\\('list_sheets:', list_sheets\\(ods\\)\\)\nprint\\('dimensions \\(Table\\):', get_sheet_dimensions\\(ods, sheet='Table'\\)\\)\nprint\\('read_cell A1 \\(Table\\):', read_cell\\(ods, 'A1', sheet='Table'\\)\\)\nprint\\('read_range A1:C3 \\(Table\\):', read_range\\(ods, 'A1:C3', sheet='Table'\\)\\)\nprint\\('search:', search_sheet\\(ods, 'sql_query', sheet='Table'\\)\\)\n\nshutil.rmtree\\(tmpdir\\)\nprint\\(\\)\nprint\\('All tool tests passed!'\\)\n\" 2>&1)",
+      "Bash(uv run python -c \"\nfrom main import add_sheet, delete_sheet, copy_sheet\n\n# CSV should reject multi-sheet operations\nimport tempfile, os\nfrom backends import create_workbook\n\ntmpdir = tempfile.mkdtemp\\(\\)\npath = f'{tmpdir}/test.csv'\nwb = create_workbook\\(path\\)\nwb.save\\(path\\)\n\nerrors = []\nfor op_name, op in [\\('add_sheet', lambda: add_sheet\\(path, 'new'\\)\\),\n                     \\('delete_sheet', lambda: delete_sheet\\(path, 'default'\\)\\),\n                     \\('copy_sheet', lambda: copy_sheet\\(path, 'default'\\)\\)]:\n    try:\n        op\\(\\)\n        errors.append\\(f'{op_name} should have raised'\\)\n    except ValueError as e:\n        print\\(f'{op_name} correctly raised: {e}'\\)\n\nimport shutil\nshutil.rmtree\\(tmpdir\\)\n\nif errors:\n    print\\('FAILURES:', errors\\)\nelse:\n    print\\('CSV sheet constraints OK'\\)\n\" 2>&1)",
+      "Bash(gh repo view --json nameWithOwner,name 2>&1)"
+    ]
+  }
+}

mcp_server_spreadsheet-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

mcp_server_spreadsheet-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

mcp_server_spreadsheet-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marek Rost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_spreadsheet-0.2.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: mcp-server-spreadsheet
+Version: 0.2.0
+Summary: MCP server for reading and writing spreadsheet files (.xlsx, .csv, .ods)
+Project-URL: Repository, https://github.com/marekrost/mcp-server-spreadsheet
+Author: Marek Rost
+License-Expression: MIT
+License-File: LICENSE
+Keywords: csv,duckdb,mcp,ods,spreadsheet,sql,xlsx
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Requires-Dist: duckdb>=0.10.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: odfpy>=1.4.0
+Requires-Dist: openpyxl>=3.1.0
+Description-Content-Type: text/markdown
+
+# mcp-server-spreadsheet
+
+Data-first MCP server for reading and writing spreadsheet files (`.xlsx`, `.csv`, `.ods`).
+
+## Key features
+
+- **Multi-format** — works with Excel (`.xlsx`), CSV (`.csv`), and OpenDocument (`.ods`) files through a unified tool interface.
+- **Dual mode** — cell-level workbook operations and a DuckDB-powered SQL query engine, interleaved freely on the same file.
+- **Workbook essentials** — worksheets, rows, columns, cells, search.
+- **Data-only** — preserves existing formatting but only reads and writes values.
+- **Stateless** — every call specifies `file` and `sheet` explicitly; no handles or sessions.
+- **Atomic saves** — writes go to a temp file, then `os.replace()` into the target path.
+- **Type coercion on write** — numeric strings become numbers, everything else is text.
+- **SQL across sheets** — JOINs, GROUP BY, aggregates, subqueries via in-memory DuckDB; mutations write back to the file.
+- **CSV as single-sheet workbook** — CSV files are treated as a workbook with one sheet named `default`.
+
+## Requirements
+
+- Python 3.13+
+
+## Installation
+
+### From PyPI (recommended)
+
+No local checkout needed — just configure your MCP client (see below).
+
+### From source (for development)
+
+```bash
+git clone https://github.com/marekrost/mcp-server-spreadsheet.git
+cd mcp-server-spreadsheet
+uv sync
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**Using PyPI (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uvx",
+      "args": ["mcp-server-spreadsheet"]
+    }
+  }
+}
+```
+
+**Using local source:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your `.mcp.json`:
+
+**Using PyPI (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uvx",
+      "args": ["mcp-server-spreadsheet"]
+    }
+  }
+}
+```
+
+**Using local source:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
+    }
+  }
+}
+```
+
+### Standalone (stdio transport)
+
+```bash
+# PyPI
+uvx mcp-server-spreadsheet
+
+# Local source
+uv run main.py
+```
+
+## Format notes
+
+| Format | Sheets | Formulas | Types |
+|---|---|---|---|
+| `.xlsx` | Multiple | Preserved as strings | Native (int, float, date, bool) |
+| `.ods` | Multiple | Not preserved | Native (int, float, date, bool) |
+| `.csv` | Single (`default`) | N/A | Inferred on load (int, float, text) |
+
+Sheet management tools (`add_sheet`, `delete_sheet`, `copy_sheet`) raise an error for CSV files.
+
+## Tools
+
+### Workbook Operations
+
+| Tool | Description |
+|---|---|
+| `list_workbooks` | List all spreadsheet files in a directory (non-recursive) |
+| `create_workbook_file` | Create a new empty spreadsheet file (format by extension) |
+| `copy_workbook` | Copy an existing file to a new path |
+
+### Sheet Operations
+
+| Tool | Description |
+|---|---|
+| `list_sheets` | List all sheet names in a workbook |
+| `add_sheet` | Add a new sheet (optional name and position) |
+| `rename_sheet` | Rename an existing sheet |
+| `delete_sheet` | Delete a sheet by name |
+| `copy_sheet` | Duplicate a sheet within a workbook (optional new name and position) |
+
+### Reading Data
+
+| Tool | Description |
+|---|---|
+| `read_sheet` | Read entire sheet as rows (optional row/column bounds) |
+| `read_cell` | Read a single cell value, e.g. `B3` |
+| `read_range` | Read a rectangular range, e.g. `A1:D10` |
+| `get_sheet_dimensions` | Get row and column count of the used range |
+
+### Writing Data
+
+| Tool | Description |
+|---|---|
+| `write_cell` | Write a value to a single cell |
+| `write_range` | Write a 2D array starting at a given cell |
+| `append_rows` | Append rows after the last used row |
+| `insert_rows` | Insert blank or pre-filled rows at a position (shifts rows down) |
+| `delete_rows` | Delete rows by index (shifts rows up) |
+| `clear_range` | Clear values in a range without removing rows/columns |
+| `copy_range` | Copy a block of cells to another location (optionally to a different sheet) |
+
+### Column Operations
+
+| Tool | Description |
+|---|---|
+| `insert_columns` | Insert blank columns at a position |
+| `delete_columns` | Delete columns by index |
+
+### Search
+
+| Tool | Description |
+|---|---|
+| `search_sheet` | Search for a value or regex pattern, returns matching cell references |
+
+### Table Mode (SQL)
+
+| Tool | Description |
+|---|---|
+| `describe_table` | Inspect column names, inferred types, row count, and sample values |
+| `sql_query` | Execute a read-only SQL `SELECT` (supports JOINs across sheets, GROUP BY, aggregates, subqueries) |
+| `sql_execute` | Execute `INSERT INTO`, `UPDATE`, or `DELETE FROM` — writes changes back to the file |
+
+SQL examples:
+
+```sql
+-- Filter and sort
+SELECT name, revenue FROM Sales WHERE status = 'Active' ORDER BY revenue DESC LIMIT 20
+
+-- Cross-sheet JOIN
+SELECT o.order_id, c.name FROM Orders o JOIN Customers c ON o.customer_id = c.id
+
+-- Aggregate
+SELECT department, COUNT(*) AS n, AVG(salary) AS avg FROM Employees GROUP BY department
+
+-- Mutate
+UPDATE Sales SET status = 'Closed' WHERE quarter = 'Q1' AND revenue < 1000
+DELETE FROM Logs WHERE date < '2024-01-01'
+```
+
+Sheet names with spaces must be quoted: `SELECT * FROM "Q1 Sales"`.
+
+## Common Parameters
+
+Every sheet-level tool accepts:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `file` | yes | Path to the spreadsheet file (.xlsx, .csv, or .ods) |
+| `sheet` | no | Sheet name. Defaults to the first sheet in the workbook |
+
+All row/column indices are **1-based**. Cell references use A1 notation (`A1`, `$B$2`).

mcp_server_spreadsheet-0.2.0/README.md

@@ -0,0 +1,207 @@
+# mcp-server-spreadsheet
+
+Data-first MCP server for reading and writing spreadsheet files (`.xlsx`, `.csv`, `.ods`).
+
+## Key features
+
+- **Multi-format** — works with Excel (`.xlsx`), CSV (`.csv`), and OpenDocument (`.ods`) files through a unified tool interface.
+- **Dual mode** — cell-level workbook operations and a DuckDB-powered SQL query engine, interleaved freely on the same file.
+- **Workbook essentials** — worksheets, rows, columns, cells, search.
+- **Data-only** — preserves existing formatting but only reads and writes values.
+- **Stateless** — every call specifies `file` and `sheet` explicitly; no handles or sessions.
+- **Atomic saves** — writes go to a temp file, then `os.replace()` into the target path.
+- **Type coercion on write** — numeric strings become numbers, everything else is text.
+- **SQL across sheets** — JOINs, GROUP BY, aggregates, subqueries via in-memory DuckDB; mutations write back to the file.
+- **CSV as single-sheet workbook** — CSV files are treated as a workbook with one sheet named `default`.
+
+## Requirements
+
+- Python 3.13+
+
+## Installation
+
+### From PyPI (recommended)
+
+No local checkout needed — just configure your MCP client (see below).
+
+### From source (for development)
+
+```bash
+git clone https://github.com/marekrost/mcp-server-spreadsheet.git
+cd mcp-server-spreadsheet
+uv sync
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+**Using PyPI (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uvx",
+      "args": ["mcp-server-spreadsheet"]
+    }
+  }
+}
+```
+
+**Using local source:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your `.mcp.json`:
+
+**Using PyPI (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uvx",
+      "args": ["mcp-server-spreadsheet"]
+    }
+  }
+}
+```
+
+**Using local source:**
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-spreadsheet": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
+    }
+  }
+}
+```
+
+### Standalone (stdio transport)
+
+```bash
+# PyPI
+uvx mcp-server-spreadsheet
+
+# Local source
+uv run main.py
+```
+
+## Format notes
+
+| Format | Sheets | Formulas | Types |
+|---|---|---|---|
+| `.xlsx` | Multiple | Preserved as strings | Native (int, float, date, bool) |
+| `.ods` | Multiple | Not preserved | Native (int, float, date, bool) |
+| `.csv` | Single (`default`) | N/A | Inferred on load (int, float, text) |
+
+Sheet management tools (`add_sheet`, `delete_sheet`, `copy_sheet`) raise an error for CSV files.
+
+## Tools
+
+### Workbook Operations
+
+| Tool | Description |
+|---|---|
+| `list_workbooks` | List all spreadsheet files in a directory (non-recursive) |
+| `create_workbook_file` | Create a new empty spreadsheet file (format by extension) |
+| `copy_workbook` | Copy an existing file to a new path |
+
+### Sheet Operations
+
+| Tool | Description |
+|---|---|
+| `list_sheets` | List all sheet names in a workbook |
+| `add_sheet` | Add a new sheet (optional name and position) |
+| `rename_sheet` | Rename an existing sheet |
+| `delete_sheet` | Delete a sheet by name |
+| `copy_sheet` | Duplicate a sheet within a workbook (optional new name and position) |
+
+### Reading Data
+
+| Tool | Description |
+|---|---|
+| `read_sheet` | Read entire sheet as rows (optional row/column bounds) |
+| `read_cell` | Read a single cell value, e.g. `B3` |
+| `read_range` | Read a rectangular range, e.g. `A1:D10` |
+| `get_sheet_dimensions` | Get row and column count of the used range |
+
+### Writing Data
+
+| Tool | Description |
+|---|---|
+| `write_cell` | Write a value to a single cell |
+| `write_range` | Write a 2D array starting at a given cell |
+| `append_rows` | Append rows after the last used row |
+| `insert_rows` | Insert blank or pre-filled rows at a position (shifts rows down) |
+| `delete_rows` | Delete rows by index (shifts rows up) |
+| `clear_range` | Clear values in a range without removing rows/columns |
+| `copy_range` | Copy a block of cells to another location (optionally to a different sheet) |
+
+### Column Operations
+
+| Tool | Description |
+|---|---|
+| `insert_columns` | Insert blank columns at a position |
+| `delete_columns` | Delete columns by index |
+
+### Search
+
+| Tool | Description |
+|---|---|
+| `search_sheet` | Search for a value or regex pattern, returns matching cell references |
+
+### Table Mode (SQL)
+
+| Tool | Description |
+|---|---|
+| `describe_table` | Inspect column names, inferred types, row count, and sample values |
+| `sql_query` | Execute a read-only SQL `SELECT` (supports JOINs across sheets, GROUP BY, aggregates, subqueries) |
+| `sql_execute` | Execute `INSERT INTO`, `UPDATE`, or `DELETE FROM` — writes changes back to the file |
+
+SQL examples:
+
+```sql
+-- Filter and sort
+SELECT name, revenue FROM Sales WHERE status = 'Active' ORDER BY revenue DESC LIMIT 20
+
+-- Cross-sheet JOIN
+SELECT o.order_id, c.name FROM Orders o JOIN Customers c ON o.customer_id = c.id
+
+-- Aggregate
+SELECT department, COUNT(*) AS n, AVG(salary) AS avg FROM Employees GROUP BY department
+
+-- Mutate
+UPDATE Sales SET status = 'Closed' WHERE quarter = 'Q1' AND revenue < 1000
+DELETE FROM Logs WHERE date < '2024-01-01'
+```
+
+Sheet names with spaces must be quoted: `SELECT * FROM "Q1 Sales"`.
+
+## Common Parameters
+
+Every sheet-level tool accepts:
+
+| Parameter | Required | Description |
+|---|---|---|
+| `file` | yes | Path to the spreadsheet file (.xlsx, .csv, or .ods) |
+| `sheet` | no | Sheet name. Defaults to the first sheet in the workbook |
+
+All row/column indices are **1-based**. Cell references use A1 notation (`A1`, `$B$2`).

mcp_server_spreadsheet-0.2.0/examples/example-free-form.csv

@@ -0,0 +1,45 @@
+"Workbook operations",
+"Tool","Description"
+"list_workbooks","List all spreadsheet files in a directory (non-recursive)"
+"create_workbook_file","Create a new empty spreadsheet file (format by extension)"
+"copy_workbook","Copy an existing file to a new path"
+,
+"Sheet operations",
+"Tool","Description"
+"list_sheets","List all sheet names in a workbook"
+"add_sheet","Add a new sheet (optional name and position)"
+"rename_sheet","Rename an existing sheet"
+"delete_sheet","Delete a sheet by name"
+"copy_sheet","Duplicate a sheet within a workbook (optional new name and position)"
+,
+"Worksheet reading",
+"Tool","Description"
+"read_sheet","Read entire sheet as rows (optional row/column bounds)"
+"read_cell","Read a single cell value, e.g. `B3`"
+"read_range","Read a rectangular range, e.g. `A1:D10`"
+"get_sheet_dimensions","Get row and column count of the used range"
+,
+"Worksheet writing",
+"Tool","Description"
+"write_cell","Write a value to a single cell"
+"write_range","Write a 2D array starting at a given cell"
+"append_rows","Append rows after the last used row"
+"insert_rows","Insert blank or pre-filled rows at a position (shifts rows down)"
+"delete_rows","Delete rows by index (shifts rows up)"
+"clear_range","Clear values in a range without removing rows/columns"
+"copy_range","Copy a block of cells to another location (optionally to a different sheet)"
+,
+"Column operations",
+"Tool","Description"
+"insert_columns","Insert blank columns at a position"
+"delete_columns","Delete columns by index"
+,
+"Search",
+"Tool","Description"
+"search_sheet","Search for a value or regex pattern, returns matching cell references"
+,
+"SQL table mode",
+"Tool","Description"
+"describe_table","Inspect column names, inferred types, row count, and sample values"
+"sql_query","Execute a read-only SQL `SELECT` (supports JOINs across sheets, GROUP BY, aggregates, subqueries)"
+"sql_execute","Execute `INSERT INTO`, `UPDATE`, or `DELETE FROM` — writes changes back to the file"

mcp_server_spreadsheet-0.2.0/examples/example-table.csv

@@ -0,0 +1,26 @@
+"Tool category","Tool","Description"
+"Workbook operations","list_workbooks","List all spreadsheet files in a directory (non-recursive)"
+"Workbook operations","create_workbook_file","Create a new empty spreadsheet file (format by extension)"
+"Workbook operations","copy_workbook","Copy an existing file to a new path"
+"Sheet operations","list_sheets","List all sheet names in a workbook"
+"Sheet operations","add_sheet","Add a new sheet (optional name and position)"
+"Sheet operations","rename_sheet","Rename an existing sheet"
+"Sheet operations","delete_sheet","Delete a sheet by name"
+"Sheet operations","copy_sheet","Duplicate a sheet within a workbook (optional new name and position)"
+"Worksheet reading","read_sheet","Read entire sheet as rows (optional row/column bounds)"
+"Worksheet reading","read_cell","Read a single cell value, e.g. `B3`"
+"Worksheet reading","read_range","Read a rectangular range, e.g. `A1:D10`"
+"Worksheet reading","get_sheet_dimensions","Get row and column count of the used range"
+"Worksheet writing","write_cell","Write a value to a single cell"
+"Worksheet writing","write_range","Write a 2D array starting at a given cell"
+"Worksheet writing","append_rows","Append rows after the last used row"
+"Worksheet writing","insert_rows","Insert blank or pre-filled rows at a position (shifts rows down)"
+"Worksheet writing","delete_rows","Delete rows by index (shifts rows up)"
+"Worksheet writing","clear_range","Clear values in a range without removing rows/columns"
+"Worksheet writing","copy_range","Copy a block of cells to another location (optionally to a different sheet)"
+"Column operations","insert_columns","Insert blank columns at a position"
+"Column operations","delete_columns","Delete columns by index"
+"Search","search_sheet","Search for a value or regex pattern, returns matching cell references"
+"SQL table mode","describe_table","Inspect column names, inferred types, row count, and sample values"
+"SQL table mode","sql_query","Execute a read-only SQL `SELECT` (supports JOINs across sheets, GROUP BY, aggregates, subqueries)"
+"SQL table mode","sql_execute","Execute `INSERT INTO`, `UPDATE`, or `DELETE FROM` — writes changes back to the file"

mcp_server_spreadsheet-0.2.0/main.py

@@ -0,0 +1,6 @@
+"""Local dev entry point — delegates to the installed package."""
+
+from mcp_server_spreadsheet.server import main
+
+if __name__ == "__main__":
+    main()

mcp_server_spreadsheet-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-server-spreadsheet"
+version = "0.2.0"
+description = "MCP server for reading and writing spreadsheet files (.xlsx, .csv, .ods)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [{ name = "Marek Rost" }]
+keywords = ["mcp", "spreadsheet", "xlsx", "csv", "ods", "duckdb", "sql"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "openpyxl>=3.1.0",
+    "duckdb>=0.10.0",
+    "odfpy>=1.4.0",
+]
+
+[project.scripts]
+mcp-server-spreadsheet = "mcp_server_spreadsheet.server:main"
+
+[project.urls]
+Repository = "https://github.com/marekrost/mcp-server-spreadsheet"
+
+[dependency-groups]
+dev = ["hatchling"]

mcp_server_spreadsheet-0.2.0/src/mcp_server_spreadsheet/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for reading and writing spreadsheet files."""
+
+__version__ = "0.2.0"

mcp_server_spreadsheet-0.2.0/src/mcp_server_spreadsheet/backends/__init__.py

@@ -0,0 +1,46 @@
+"""Spreadsheet backend factory — dispatches by file extension."""
+
+from pathlib import Path
+
+from .base import SpreadsheetWorkbook
+
+SUPPORTED_EXTENSIONS = {".xlsx", ".csv", ".ods"}
+
+
+def load_workbook(path: str) -> SpreadsheetWorkbook:
+    """Load a spreadsheet file, choosing the backend by extension."""
+    p = Path(path)
+    if not p.exists():
+        raise ValueError(f"File not found: {path}")
+    ext = p.suffix.lower()
+    if ext == ".xlsx":
+        from .xlsx import XlsxWorkbook
+        return XlsxWorkbook.load(path)
+    if ext == ".csv":
+        from .csv import CsvWorkbook
+        return CsvWorkbook.load(path)
+    if ext == ".ods":
+        from .ods import OdsWorkbook
+        return OdsWorkbook.load(path)
+    raise ValueError(
+        f"Unsupported file format: {ext!r}. "
+        f"Supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+    )
+
+
+def create_workbook(path: str, sheet_name: str | None = None) -> SpreadsheetWorkbook:
+    """Create a new empty workbook in memory, choosing the backend by extension."""
+    ext = Path(path).suffix.lower()
+    if ext == ".xlsx":
+        from .xlsx import XlsxWorkbook
+        return XlsxWorkbook.create(sheet_name)
+    if ext == ".csv":
+        from .csv import CsvWorkbook
+        return CsvWorkbook.create(sheet_name)
+    if ext == ".ods":
+        from .ods import OdsWorkbook
+        return OdsWorkbook.create(sheet_name)
+    raise ValueError(
+        f"Unsupported file format: {ext!r}. "
+        f"Supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+    )