sumoffice for Python

Open, edit, recalculate and save Excel workbooks, read Word documents and add slides to PowerPoint decks from Python. The package ships the native SumSheet, SumDoc and SumSlide cores inside the wheel: nothing is compiled on install, and you need neither Microsoft Office nor LibreOffice. To let people view and edit the documents in a browser, use SumOffice Server.

sumoffice.core_version() returns the exact packaged core release.

pip install sumoffice

Wheels exist for macOS (Apple silicon and Intel), Linux x86-64 and aarch64 (glibc 2.28 or newer) and Windows x64, for Python 3.10 and newer.

First result in five lines

import sumoffice

wb = sumoffice.open("report.xlsm")
wb["Cash flow"]["B7"] = 42
wb.save("report-edited.xlsm")

The VBA project, Power Query parts and images stay in the saved file byte for byte; sumoffice never rewrites parts it did not change.

Three examples

1. Change a cell in a macro workbook and keep the macros

import sumoffice

wb = sumoffice.open("budget.xlsm")
print(wb.sheet_names)                 # ('Cash flow', 'Summary')
wb["Cash flow"]["B7"] = 42            # number, text, None, or a formula "=B5*2"
wb.save("budget-edited.xlsm")         # vbaProject.bin is kept as it was

2. Recalculate and read the results back

import sumoffice

wb = sumoffice.open("model.xlsx")
sheet = wb["Summary"]
sheet["A1"] = 1200
sheet["A2"] = "=A1*1.2"
wb.recalc()
print(sheet["A2"])                    # 1440
print(sheet.formula("A2"))            # '=A1*1.2'
print(sheet.read("A1:B3"))            # [[1200, None], [1440, None], [None, None]]
wb.save("model-edited.xlsx")

again = sumoffice.open("model-edited.xlsx")
assert again["Summary"]["A2"] == 1440

3. Read the text of a Word document; add a slide to a deck

import sumoffice

print(sumoffice.text("contract.docx"))

deck = sumoffice.open("deck.pptx")
deck.add_slide()
print(deck.slide_count)
deck.save("deck-edited.pptx")

Show it on your own server

The library contains no viewer. Without SUMOFFICE_SERVER_URL, sumoffice.view(path) returns the real server acquisition command. With that address and SUMOFFICE_SERVER_TOKEN set, it uploads the local file to POST /sdk/v1/documents and returns the server's signed editor_url.

editor = sumoffice.view("report-edited.xlsx")
print(editor.editor_url)

Use it from Claude Desktop, Cursor or another MCP client

The package includes a local MCP server that works only with files on your computer. Nothing is sent anywhere.

{
  "mcpServers": {
    "sumoffice": { "command": "/full/path/to/venv/bin/sumoffice-mcp" }
  }
}

Desktop apps do not read your shell's PATH, so give the full path: run which sumoffice-mcp (Windows: where sumoffice-mcp) in the environment where you installed the package. In Claude Desktop the file is claude_desktop_config.json (Settings → Developer → Edit Config); restart the app after saving.

Tools: open_workbook, read_range, write_cells, recalc, save_copy, document_text. By default the server reads files under your home directory; set SUMOFFICE_MCP_ROOTS (paths separated by the OS path separator) to allow other folders. save_copy never overwrites the source file.

What is free

A document counts once per opening, however many cells you change. Request a developer key at https://sumoffice.com/python#developer-key. Put the key in SUMOFFICE_LICENSE, or the path to the key file in SUMOFFICE_LICENSE_FILE.

The daily quota is enforced by the Word core today. The spreadsheet and presentation cores do not count documents yet, so their use is currently not limited.

What it does not do

• It does not run VBA macros; it keeps them.
• XLSX to PDF conversion and page previews are not in this wheel yet: sumoffice.convert() and sumoffice.preview() raise CapabilityUnavailableError and create no file.
• Word support is read-only in the high-level API (sumoffice.text); editing goes through the low-level Session.
• The Word core uses system fonts. On a server without fonts set FASTDOC_FONT_DIR to a folder with the document's fonts for stable layout.
• A wheel works only on the operating system and CPU named in its file name.
• Error messages are in Russian in this release.

Low level

sumoffice.Session opens a document in one core and accepts the core's own JSON commands. Engines are called "sheet", "doc" and "slide" (the names "sumsheet", "sumdoc" and "sumslide" also work). Call session.handshake() to see the operations a core supports.

Documentation and support

• Documentation: https://sumoffice.com/python
• Support: hello@sumoffice.com
• Terms: see LICENSE.txt in the package.