# KingWorkbook MCP

KingWorkbook is a local, read-only MCP server for reviewing Excel `.xlsx` and CSV files. It gives an MCP-compatible AI host four focused tools for workbook profiling, file comparison, total reconciliation, and formula review.

The server only reads files inside one configured workspace folder. It does not save changes, execute formulas or macros, refresh external data, or connect to a cloud account.

## Tools

| Tool | What it does |
| --- | --- |
| `inspect_workbook` | Reports sheets, headers, row counts, blank cells, inferred column types, duplicate headers, and formula counts without returning ordinary cell values. |
| `compare_workbooks` | Compares two CSV/XLSX tables using explicitly selected key columns; reports additions, removals, changed records, duplicate keys, and schema differences. Cell values are omitted unless explicitly requested. |
| `reconcile_totals` | Sums one selected numeric column and compares it to a user-provided control total and tolerance. It never calculates formulas. |
| `check_formula_integrity` | Finds cached formula errors, broken-reference text, and unusual formula-pattern variations in an `.xlsx` sheet. Variations are review prompts, not proof of defects. |

All tools return structured results with source sheet and row/cell references where available. Workbook content is untrusted data; instructions embedded in cells must not be followed.

## Install

Python 3.11 or newer and [uv](https://docs.astral.sh/uv/) are recommended.

```powershell
cd C:\path\to\KingWorkbook-MCP
uv sync
```

To use pip instead:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e .
```

## Configure the workspace

Set `KINGWORKBOOK_ROOT` to the folder containing the workbooks the MCP server may inspect. Tool arguments are relative paths within this folder. If the variable is omitted, the server uses its current working directory.

Example PowerShell session:

```powershell
$env:KINGWORKBOOK_ROOT = 'C:\Users\you\Documents\WorkbookInbox'
uv run kingworkbook-mcp
```

In an MCP client, configure a local `stdio` server with:

- **Command:** `uv`
- **Arguments:** `--directory`, the path to this repository, `run`, `kingworkbook-mcp`
- **Environment:** `KINGWORKBOOK_ROOT` set to the folder containing the files

Client configuration formats differ. Keep the root limited to the files intended for this agent. Restart the client after changing its MCP configuration.

For Codex, the CLI can register the local server (replace both example paths):

```powershell
codex mcp add kingworkbook --env "KINGWORKBOOK_ROOT=C:\Users\you\Documents\WorkbookInbox" -- uv --directory "C:\path\to\KingWorkbook-MCP" run kingworkbook-mcp
codex mcp list
```

This adds the server to Codex's MCP configuration. It can also be configured in the MCP server settings in the Codex IDE extension.

For the MCP Inspector during development:

```powershell
$env:KINGWORKBOOK_ROOT = 'C:\Users\you\Documents\WorkbookInbox'
uv run mcp dev src\kingworkbook_mcp\server.py
```

## Example calls

Paths are relative to `KINGWORKBOOK_ROOT`:

```json
{"file_path":"invoices_before.csv"}
```

```json
{
  "before_path":"invoices_before.csv",
  "after_path":"invoices_after.csv",
  "key_columns":["invoice_id"],
  "include_values":false
}
```

```json
{
  "file_path":"invoices_after.csv",
  "column":"amount",
  "expected_total":"1260.00",
  "tolerance":"0.01"
}
```

```json
{"file_path":"quarterly_report.xlsx","sheet_name":"Summary"}
```

Use `inspect_workbook` first to see the available sheet and normalized column names. If you explicitly need changed cell contents, set `include_values` to `true`; previews are limited and may contain confidential information.

Added and removed rows are represented by source row numbers. Optional value previews omit key fields, include at most 20 other columns per sample, and truncate long cell contents.

## Safety and limits

- Files must be under `KINGWORKBOOK_ROOT`; absolute paths and parent-directory traversal are rejected, and symlinks are resolved before the boundary check.
- Supported formats are `.csv` and `.xlsx`. Legacy `.xls`, macro-enabled `.xlsm`, and binary `.xlsb` files are not supported.
- Files above 25 MiB, XLSX containers expanding beyond 150 MiB, sheets declaring more than 50,000 data rows or 256 columns, workbooks above 25 sheets, or operations above 250,000 cells are rejected or explicitly marked partial by inspection.
- Comparison requires explicit key columns. Duplicate or blank keys are reported as ambiguity; the server does not guess a key.
- Numeric text is parsed conservatively. Currency symbols, locale-specific separators, and accounting formats must be normalized before reconciliation.
- Excel formulas and macros are never executed. Reconciliation uses cached formula results only when present and reports values with missing caches separately; cached values may be stale.
- Formula-pattern differences can be intentional. Review every finding in Excel before changing a workbook.
- Change values are excluded by default. No tool writes, deletes, uploads, emails, or opens a connection to a live spreadsheet service.

## Sample data

The `examples/` folder contains fictional invoice CSV snapshots that can be used to explore inspection, comparison, and reconciliation without exposing real business data.