Excel Workbook Conversion

import { Aside } from ‘@astrojs/starlight/components’;

Excel workbook conversion turns an existing spreadsheet model into a Bridge Town Python project you can version, run, and share. This is a different feature from Excel as a data table — read that section first if you are not sure which one you need.

Excel as a data table vs. Excel model conversion

Bridge Town has two separate pathways for Excel files. Choose the right one for your situation.

I want to…	Use this path
Query rows and columns from an Excel sheet (revenue table, actuals, headcount roster)	`ingest_data_source` with `kind: "file_upload"` — stores the sheet as a queryable Parquet snapshot
Convert an Excel financial model (formulas, sheets, named ranges, dependencies) into Bridge Town Python	Excel workbook conversion — this guide

Using ingest_data_source on a workbook with formulas stores the cached cell values only. It does not translate formulas, preserve workbook structure, or produce Python code. Use workbook conversion when the formulas themselves are what you want to migrate.

What v1 supports

Supported workbook features

.xlsx and .xlsm files (macros are detected and listed as findings, not executed)
One or more worksheets with visible cell values and formulas
Named ranges and Excel tables where present
Common FP&A formulas: arithmetic, SUM, AVERAGE, MIN, MAX, IF, IFS, SUMIF, SUMIFS, COUNTIF, COUNTIFS, XLOOKUP, VLOOKUP, INDEX, MATCH, ROUND, NPV, IRR, PMT, date arithmetic, and basic text/date helpers
Cached formula values read from the workbook for parity comparison

What is surfaced in findings, not converted

The following features appear in the conversion report under Findings, but are not converted to Python. Review the findings before applying generated files and plan manual replacements for any your model relies on.

Feature	Reason
VBA macros and `.xlsm` macro modules	Not executed — inert parse only
External workbook links	Cannot resolve at conversion time
Power Query, pivot tables, data model, slicers	Not yet supported in v1
Dynamic arrays (where parser support is limited)	Partial support — verify output
Circular references and iterative calculation	Listed as findings; conversion skips affected cells
Volatile functions: `NOW`, `TODAY`, `RAND`, `RANDBETWEEN`, `OFFSET`, `INDIRECT`	Runtime-dependent; safe static equivalents flagged for review
Protected or encrypted workbooks	Cannot inspect — conversion blocked
External data refreshes and web formulas	Not resolved at conversion time

Hidden sheets are profiled and listed in findings rather than silently ignored.

Size and budget limits

Limit	Default
Maximum raw file size	50 MB
Maximum workbook zip size	25 MB
Maximum sheet count	50
Maximum cell count	500 000
Maximum formula count	100 000

Contact support@bridgetown.builders if your workbook is near or above these limits.

Upload options

Option 1 — Browser upload (recommended)

Open app.bridgetown.builders and go to Data Sources (/data).
Click Upload file on the Upload file card.
In the upload dialog, select a project, enter a source name, then drop or browse to your .xlsx or .xlsm file (max 50 MB).
After the file is accepted, you will see an inline hint: “To convert the workbook logic into runnable models, Convert the logic instead.” Click Convert the logic to switch to the Excel Conversion wizard. Alternatively, click Upload first — after the upload completes, the review screen shows a Workbook inspection panel with the same Convert the logic link.
Bridge Town creates a conversion job. You can track progress in the wizard or close it — the job continues in the background and appears in the running conversions banner on /data.

This option works for all users regardless of which MCP host or client they use. It does not require the workbook bytes to pass through an MCP tool call.

Option 2 — Upload link (for Claude.ai and MCP-connected agents)

Claude.ai and similar hosts cannot send large binary files through tool arguments without consuming substantial context. For these hosts, Bridge Town provides a short-lived, single-use upload link:

The agent requests an upload session:
```
POST /api/projects/{project}/excel-conversions/upload-sessions
```
Bridge Town returns an upload_url, a staged_upload_id, and an expiry time.
Claude.ai presents the upload link to the user. The user opens the link in their browser, uploads the workbook file, and returns to the conversation.
The agent continues the conversion using only the staged_upload_id — no workbook bytes pass through the tool call.

Upload sessions are:

Scoped to the requesting tenant, user, and project
Single-use: the link becomes invalid after one successful upload
Short-lived: default expiry is 30 minutes
Size-capped and MIME-type enforced (.xlsx / .xlsm only)
Audited: every session create, upload, and expiry is logged

Option 3 — URL-pull ingress (optional, restricted)

If the workbook already exists at an HTTPS download URL you control, an operator can configure URL-pull ingress. This path has strict security requirements — see the operator runbook for allowed URL patterns and SSRF guards.

User flow: from upload to dashboard

Upload — use browser upload or the upload link path above.
Profile — Bridge Town parses the workbook (inert, no code is executed) and produces a workbook profile:
- sheet names and row/column extents
- named ranges and Excel tables
- formula dependency graph
- supported vs. unsupported formula list
- hidden sheets and external links
Review — open the conversion report in the web app. Review:
- the list of findings for unsupported or volatile formulas
- the generated Python files (drivers.py, calculations.py, outputs.py, tests/test_parity.py, README.md)
- parity checks: generated outputs compared to cached Excel values
- dashboard candidates mapped from converted outputs
Apply — after reviewing, click Apply (or confirm via MCP) to write the selected generated files to your project. Files are applied to a branch and require explicit confirmation — they are never auto-merged.
Run — run the generated project to produce output files.
Dashboard — create dashboards from run outputs using existing create_dashboard.

Nothing is applied to your project until you explicitly confirm.

What to review before applying

Findings — any unsupported or volatile formula your model depends on needs a manual replacement. The README.md in the generated output lists each finding with a suggested approach.
Parity report — the tests/test_parity.py file compares generated Python outputs to cached Excel values. Run the tests after applying to see pass/fail with tolerances. A parity gap does not necessarily mean the conversion is wrong — Excel may have had stale cached values.
Formula translation — read calculations.py for any complex formula. Automated translation prioritises readability over cell-by-cell fidelity.
Named ranges and assumptions — drivers.py lists assumptions and imported workbook values. Confirm the names and default values match your intent.
Secrets and sensitive data — the conversion scanner flags cell contents that look like credentials, connection strings, or tokens. Do not upload workbooks containing plaintext secrets. See Security notes below.

Agent and MCP workflow

Agents use the conversion workflow through existing tools only. No new MCP tool name is introduced for workbook conversion.

Recommended agent sequence:

# 1. If the workbook is not yet uploaded, request an upload session
#    and present the link to the user.
#    (REST call — not a tool call)

# 2. Once the user has uploaded (or a staged_upload_id is available),
#    start a conversion job.
#    Extend ingest_data_source or use the REST endpoint with the staged id.

# 3. Poll job status (REST) until the conversion profile is ready.

# 4. Retrieve the generated file index from the job result.

# 5. Use existing file tools to apply selected files after user confirmation.
create_file(project_name="{{ project_name }}", path="model/conversion/drivers.py", content="...")
update_file(...)
commit_files(project_name="{{ project_name }}", message="feat: apply Excel conversion (reviewed)")

# 6. Run the generated project.
run(project_name="{{ project_name }}")
get_run(project_name="{{ project_name }}", run_id="...")

# 7. Create dashboards from run outputs.
create_dashboard(project_name="{{ project_name }}", ...)
share_dashboard(project_name="{{ project_name }}", ...)

Use get_skill to load the convert_excel_workbook bundled skill for a step-by-step agent prompt:

{"name": "get_skill", "arguments": {"name": "convert_excel_workbook", "include_template": true}}

The skill is also discoverable through search_tools:

{"name": "search_tools", "arguments": {"query": "convert excel workbook", "domain": "skills"}}

Security notes

Do not upload workbooks that contain passwords, API tokens, database connection strings, or other secrets in cells or connection metadata. The conversion scanner flags suspicious strings, but it is not a substitute for reviewing the workbook before upload.
Do not instruct users to paste workbook bytes into Claude.ai or an MCP tool call. Use the browser upload or upload link path instead.
Do not enable macros in a workbook before uploading — macros are detected and listed as findings, not executed. An .xlsm file is parsed as inert data.
Do not bypass the parity review step before applying generated files. The parity report exists to catch silent mistranslations.
Upload links are single-use and expire after 30 minutes. Do not share an upload link with anyone other than the intended user.

Limitations and honest expectations

Workbook conversion is a first-pass migration aid, not a guaranteed correct replica. Expect to:

Replace volatile formulas (NOW, TODAY, RAND) with static inputs or runtime parameters.
Manually handle formulas in the findings list (external links, Power Query, macros, complex dynamic arrays).
Review parity gaps — even small tolerances may indicate a logic difference worth investigating.
Rename generated functions for clarity before sharing the project with teammates.

For workbooks with complex VBA, extensive external data connections, or very large formula graphs, budget additional review time proportional to the findings count.

Page	Why it’s useful
Data Integrations	Full guide to bringing data into Bridge Town — includes the `ingest_data_source` file-upload path for Excel as a data table.
`ingest_data_source`	Tool reference for CSV/Excel table ingestion (not workbook conversion).
MCP Skills Resources	How to discover and load the `convert_excel_workbook` bundled skill.
Dashboards	Creating and sharing dashboards from model run outputs.
Excel Conversion Operator Runbook	Job phases, failure codes, artifact cleanup, and security-sensitive logging for operators.
support@bridgetown.builders	Help with oversized workbooks, URL-pull setup, or conversion failures.