mcp-server-spreadsheet

Instructions

Implementation Reference

• src/mcp_server_spreadsheet/server.py:473-498 (handler)

  The implementation of the search_sheet tool, which searches for a regex pattern within a spreadsheet and returns matching cell references and values.

  def search_sheet(
      file: Annotated[str, Field(description="Path to the spreadsheet file")],
      pattern: Annotated[str, Field(description="Regular expression pattern to search for. Matched against the string representation of each cell value.")],
      sheet: Annotated[str | None, Field(description="Sheet name. Defaults to the first sheet if omitted.")] = None,
  ) -> list[dict]:
      """Search all cells in a sheet for values matching a regex pattern.
  
      Returns a list of matches, each with the cell reference and value,
      e.g. [{"cell": "B3", "value": "hello"}, ...]. Returns an empty list
      if no matches are found.
      """
      wb = load_workbook(file)
      ws = _resolve_sheet(wb, sheet)
      regex = re.compile(pattern)
      results = []
      for r in range(1, ws.max_row + 1):
          for c in range(1, ws.max_column + 1):
              val = ws.cell_value(r, c)
              if val is None:
                  continue
              if regex.search(str(val)):
                  results.append({
                      "cell": f"{get_column_letter(c)}{r}",
                      "value": val,
                  })
      return results