mcp-win-stdio-excel 0.2.3__tar.gz

mcp_win_stdio_excel-0.2.3/.gitignore

@@ -0,0 +1,60 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+*.manifest
+*.spec
+api.txt
+pip-log.txt
+pip-delete-this-directory.txt
+pypi api.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+*.mo
+*.pot
+
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+
+*.log

mcp_win_stdio_excel-0.2.3/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: mcp-win-stdio-excel
+Version: 0.2.3
+Summary: Windows-optimized Model Context Protocol (MCP) server for Excel: 20 tools for Pandas queries, RapidFuzz reconciliation, cell editing, and native Excel COM automation (PDF export, recalc, pivots, macros).
+Author-email: indala <indala@example.com>
+License-Expression: MIT
+Keywords: ai,claude,excel,llm,mcp,openpyxl,pandas,reconciliation,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.10
+Requires-Dist: mcp-win-stdio>=0.2.3
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pywin32>=306; platform_system == 'Windows'
+Requires-Dist: rapidfuzz>=3.0.0
+Description-Content-Type: text/markdown
+
+# mcp-win-stdio-excel
+
+Windows-native **Model Context Protocol (MCP)** server for Microsoft Excel: 20 tools combining high-speed Pandas querying, RapidFuzz reconciliation, OpenPyXL editing, and native Windows Excel COM automation.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (20 Tools)
+
+- **Vectorized Data Queries**: High-speed Pandas slicing, filtering, and aggregation on large spreadsheets.
+- **Typo-Tolerant Reconciliation**: Pre-flight key diagnostics (`analyze_reconciliation_keys`) and fuzzy joins (`reconcile_and_merge`) producing clean 3-tab audit workbooks (`Matched`, `Unmatched_Source`, `Unmatched_Target`).
+- **OpenPyXL Direct Editing**: Safe cell updates, row appending, multi-sheet management, formula insertion, CSV/JSON export.
+- **Native Windows Excel COM Automation**: Background/visible Excel process control, formula recalculation, pivot table refreshes, PDF export, and VBA macro execution.
+
+---
+
+## 🛠️ Included Tools (20 Tools)
+
+* **Inspection**: `get_workbook_info`, `preview_sheet`, `get_column_values`, `compare_column_values`, `summarize_column`, `search_text`.
+* **Querying & Slices**: `query_rows` (Pandas vectorized expressions), `read_range`, `query_excel_sql`.
+* **Editing & Export**: `create_workbook`, `append_rows`, `update_cells`, `add_sheet`, `rename_sheet`, `delete_sheet`, `export_to_csv`, `export_to_json`.
+* **Reconciliation**: `analyze_reconciliation_keys`, `reconcile_and_merge`.
+* **Windows COM Automation**: `recalculate_and_save`, `export_to_pdf`, `refresh_data_and_pivots`, `run_vba_macro`, `get_active_excel_window`.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-excel
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup excel
+# or:
+mws add excel
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.excel"]
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws excel guide     # Complete tool reference & prompt recipes
+mws excel doctor    # Verify Excel COM automation, Pandas, and OpenPyXL
+mws excel setup     # Configure Claude Desktop / Claude Code
+mws excel run       # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_excel-0.2.3/README.md

@@ -0,0 +1,72 @@
+# mcp-win-stdio-excel
+
+Windows-native **Model Context Protocol (MCP)** server for Microsoft Excel: 20 tools combining high-speed Pandas querying, RapidFuzz reconciliation, OpenPyXL editing, and native Windows Excel COM automation.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (20 Tools)
+
+- **Vectorized Data Queries**: High-speed Pandas slicing, filtering, and aggregation on large spreadsheets.
+- **Typo-Tolerant Reconciliation**: Pre-flight key diagnostics (`analyze_reconciliation_keys`) and fuzzy joins (`reconcile_and_merge`) producing clean 3-tab audit workbooks (`Matched`, `Unmatched_Source`, `Unmatched_Target`).
+- **OpenPyXL Direct Editing**: Safe cell updates, row appending, multi-sheet management, formula insertion, CSV/JSON export.
+- **Native Windows Excel COM Automation**: Background/visible Excel process control, formula recalculation, pivot table refreshes, PDF export, and VBA macro execution.
+
+---
+
+## 🛠️ Included Tools (20 Tools)
+
+* **Inspection**: `get_workbook_info`, `preview_sheet`, `get_column_values`, `compare_column_values`, `summarize_column`, `search_text`.
+* **Querying & Slices**: `query_rows` (Pandas vectorized expressions), `read_range`, `query_excel_sql`.
+* **Editing & Export**: `create_workbook`, `append_rows`, `update_cells`, `add_sheet`, `rename_sheet`, `delete_sheet`, `export_to_csv`, `export_to_json`.
+* **Reconciliation**: `analyze_reconciliation_keys`, `reconcile_and_merge`.
+* **Windows COM Automation**: `recalculate_and_save`, `export_to_pdf`, `refresh_data_and_pivots`, `run_vba_macro`, `get_active_excel_window`.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-excel
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup excel
+# or:
+mws add excel
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.excel"]
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws excel guide     # Complete tool reference & prompt recipes
+mws excel doctor    # Verify Excel COM automation, Pandas, and OpenPyXL
+mws excel setup     # Configure Claude Desktop / Claude Code
+mws excel run       # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_excel-0.2.3/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-win-stdio-excel"
+version = "0.2.3"
+description = "Windows-optimized Model Context Protocol (MCP) server for Excel: 20 tools for Pandas queries, RapidFuzz reconciliation, cell editing, and native Excel COM automation (PDF export, recalc, pivots, macros)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "indala", email = "indala@example.com" }
+]
+keywords = ["mcp", "claude", "excel", "pandas", "openpyxl", "reconciliation", "windows", "ai", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+]
+
+dependencies = [
+    "mcp-win-stdio>=0.2.3",
+    "mcp>=1.2.0",
+    "pandas>=2.0.0",
+    "openpyxl>=3.1.0",
+    "rapidfuzz>=3.0.0",
+    "pywin32>=306; platform_system == 'Windows'",
+]
+
+[project.scripts]
+mcp-win-stdio-excel = "mcp_win_stdio.excel.cli:main"
+mws-excel = "mcp_win_stdio.excel.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_win_stdio"]

mcp_win_stdio_excel-0.2.3/src/mcp_win_stdio/excel/__init__.py

@@ -0,0 +1,5 @@
+"""
+mcp-win-stdio-excel: Windows-optimized Excel MCP Server.
+"""
+
+__version__ = "0.2.3"

mcp_win_stdio_excel-0.2.3/src/mcp_win_stdio/excel/__main__.py

@@ -0,0 +1,8 @@
+"""
+Direct module execution for mcp_win_stdio.excel.
+"""
+
+from mcp_win_stdio.excel.server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

mcp_win_stdio_excel-0.2.3/src/mcp_win_stdio/excel/cli.py

@@ -0,0 +1,186 @@
+"""
+CLI entry point for mcp-win-stdio-excel.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+from mcp_win_stdio.excel import __version__
+from mcp_win_stdio.excel.guide import print_guide
+from mcp_win_stdio.excel.server import mcp
+
+
+def get_claude_desktop_config_path() -> Path | None:
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        p = Path(appdata) / "Claude" / "claude_desktop_config.json"
+        if p.exists():
+            return p
+    default_p = Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    return default_p if default_p.exists() else None
+
+
+def get_claude_cli_config_path() -> Path | None:
+    p = Path.home() / ".claude.json"
+    return p if p.exists() else None
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    """Setup excel MCP server in Claude Desktop and Claude Code CLI."""
+    client = args.client.lower()
+    python_exe = sys.executable.replace("\\", "/")
+    cmd_args = ["-m", "mcp_win_stdio.excel.server"]
+
+    print(f"\nSetting up 'excel' MCP server (target: {client})...\n")
+
+    # 1. Desktop
+    if client in ("all", "desktop"):
+        desktop_cfg = get_claude_desktop_config_path()
+        if desktop_cfg:
+            try:
+                shutil.copy2(desktop_cfg, desktop_cfg.with_suffix(".json.bak"))
+                with open(desktop_cfg, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if "mcpServers" not in data:
+                    data["mcpServers"] = {}
+                data["mcpServers"]["excel"] = {
+                    "command": python_exe,
+                    "args": cmd_args,
+                }
+                with open(desktop_cfg, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+                print(f"[OK] Claude Desktop: Configured 'excel' in {desktop_cfg}")
+            except Exception as e:
+                print(f"[ERROR] Claude Desktop: Failed to configure: {e}")
+        else:
+            print("[WARN] Claude Desktop configuration not found.")
+
+    # 2. CLI
+    if client in ("all", "cli"):
+        added_cli = False
+        try:
+            res = subprocess.run(
+                ["claude", "mcp", "add", "-s", "user", "excel", "--", python_exe] + cmd_args,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if res.returncode == 0:
+                added_cli = True
+                print("[OK] Claude Code CLI: Configured via `claude mcp add`")
+        except Exception:
+            pass
+
+        if not added_cli:
+            cli_cfg = get_claude_cli_config_path()
+            if cli_cfg:
+                try:
+                    with open(cli_cfg, "r", encoding="utf-8") as f:
+                        cli_data = json.load(f)
+                    if "mcpServers" not in cli_data:
+                        cli_data["mcpServers"] = {}
+                    cli_data["mcpServers"]["excel"] = {
+                        "command": python_exe,
+                        "args": cmd_args,
+                    }
+                    with open(cli_cfg, "w", encoding="utf-8") as f:
+                        json.dump(cli_data, f, indent=2)
+                    print(f"[OK] Claude Code CLI: Configured directly in {cli_cfg}")
+                except Exception as e:
+                    print(f"[ERROR] Claude CLI: Failed to configure: {e}")
+
+    print("\nExcel MCP setup complete! Please restart Claude Desktop if active.\n")
+
+
+def cmd_remove(args: argparse.Namespace) -> None:
+    """Remove excel MCP server from Claude Desktop and CLI."""
+    desktop_cfg = get_claude_desktop_config_path()
+    if desktop_cfg and desktop_cfg.exists():
+        try:
+            with open(desktop_cfg, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            if "mcpServers" in data and "excel" in data["mcpServers"]:
+                del data["mcpServers"]["excel"]
+                with open(desktop_cfg, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+                print(f"[OK] Removed 'excel' from Claude Desktop.")
+        except Exception as e:
+            print(f"[ERROR] Claude Desktop: {e}")
+
+    try:
+        res = subprocess.run(["claude", "mcp", "remove", "-s", "user", "excel"], capture_output=True, text=True)
+        if res.returncode == 0:
+            print("[OK] Removed 'excel' from Claude Code CLI.")
+    except Exception:
+        pass
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run excel MCP server over stdio."""
+    mcp.run()
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Check Excel MCP health and dependencies."""
+    print(f"\n=== mcp-win-stdio-excel Doctor Diagnostic (v{__version__}) ===\n")
+    print(f"[OK] Python: {sys.version.split()[0]} ({sys.executable})")
+
+    for dep in ("mcp", "pandas", "openpyxl", "rapidfuzz", "win32com"):
+        try:
+            __import__(dep)
+            print(f"[OK] Dependency: {dep:<12}")
+        except ImportError:
+            print(f"[FAIL] Dependency: {dep:<12} (MISSING)")
+
+    print("\n--- Excel COM Automation Check ---")
+    try:
+        import win32com.client
+        app = win32com.client.DispatchEx("Excel.Application")
+        ver = app.Version
+        app.Quit()
+        print(f"[OK] Microsoft Excel COM: Available (Version {ver})")
+    except Exception as e:
+        print(f"[INFO] Microsoft Excel COM: Not detected ({e})")
+
+    print("\nDiagnostic complete.\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-win-stdio-excel",
+        description="Windows-optimized Excel MCP Server CLI",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    sub_setup = subparsers.add_parser("setup", help="Auto-configure into Claude Desktop & CLI")
+    sub_setup.add_argument("--client", "-c", choices=["all", "desktop", "cli"], default="all")
+    sub_setup.set_defaults(func=cmd_setup)
+
+    sub_remove = subparsers.add_parser("remove", help="Remove from Claude Desktop & CLI")
+    sub_remove.set_defaults(func=cmd_remove)
+
+    sub_guide = subparsers.add_parser("guide", help="View usage guide and prompt recipes")
+    sub_guide.set_defaults(func=lambda args: print_guide())
+
+    sub_run = subparsers.add_parser("run", help="Run Excel MCP server over stdio")
+    sub_run.set_defaults(func=cmd_run)
+
+    sub_doctor = subparsers.add_parser("doctor", help="Check dependencies and COM automation")
+    sub_doctor.set_defaults(func=cmd_doctor)
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio_excel-0.2.3/src/mcp_win_stdio/excel/guide.py

@@ -0,0 +1,69 @@
+"""
+Interactive and printable guide for the Excel MCP server.
+"""
+
+EXCEL_GUIDE = """
+# ================================================================
+# EXCEL MCP (WINDOWS NATIVE + PANDAS) - USER & LLM GUIDE
+# ================================================================
+
+The Excel MCP server provides 20 specialized tools for programmatic
+reading, updating, querying, fuzzy reconciling, and automating Excel
+workbooks on Windows.
+
+----------------------------------------------------------------
+1. TOOL SUMMARY
+----------------------------------------------------------------
+* Read & Inspect:
+  - get_workbook_info(file_path): Sheet names, dimensions, cell counts.
+  - preview_sheet(file_path, sheet_name, max_rows): Fast preview.
+  - query_rows(file_path, sheet_name, query_expr, columns): Pandas query.
+  - read_range(file_path, sheet_name, range_address): Slices (e.g. A1:D50).
+  - summarize_column(file_path, sheet_name, column_name): Statistics.
+  - search_text(file_path, sheet_name, search_term): Keyword search.
+
+* Edit & Manage:
+  - create_workbook(file_path, sheet_name, headers, initial_rows): Create xlsx.
+  - append_rows(file_path, sheet_name, rows): In-place fast row append.
+  - update_cells(file_path, sheet_name, updates): Set values & formulas.
+  - add_sheet(file_path, sheet_name, title): Add new worksheet.
+  - rename_sheet(file_path, old_name, new_name): Rename worksheet.
+  - delete_sheet(file_path, sheet_name): Delete worksheet.
+  - export_to_csv(file_path, sheet_name, output_csv_path): CSV export.
+
+* Reconciliation & Audit:
+  - analyze_reconciliation_keys(wb1, s1, keys1, wb2, s2, keys2):
+    PRE-FLIGHT analysis. Checks nulls, duplicate keys, overlap %, and
+    candidate fuzzy matches before any merging is performed!
+  - reconcile_and_merge(wb1, s1, keys1, wb2, s2, keys2, output_wb, fuzzy_matching=True):
+    Generates an automated 3-tab audit workbook:
+    [1] Matched (exact + fuzzy with confidence scores & variance)
+    [2] Unmatched_Source_1
+    [3] Unmatched_Source_2
+
+* Native Windows Excel COM Automation (Requires installed Excel):
+  - recalculate_and_save(file_path): Forces formula engine calculation.
+  - export_to_pdf(file_path, output_pdf_path): Native high-res PDF export.
+  - refresh_data_and_pivots(file_path): Refreshes PowerQuery / Pivot tables.
+  - run_vba_macro(file_path, macro_name): Executes workbook VBA macros.
+  - get_active_excel_window(): Inspects open Excel instances.
+
+----------------------------------------------------------------
+2. EXAMPLE PROMPTS FOR CLAUDE
+----------------------------------------------------------------
+* Pre-flight Check:
+  "Analyze the reconciliation keys between orders.xlsx (sheet: Sheet1,
+  keys: PO_Number, Vendor) and sap_report.xlsx (sheet: PR_Data,
+  keys: SAP_PO, Vendor_ID) and tell me match rate and fuzzy candidates."
+
+* Reconcile:
+  "Reconcile those workbooks into audit_result.xlsx with fuzzy matching
+  enabled and show me the unmatched items."
+
+* COM Automation:
+  "Recalculate formulas in audit_result.xlsx and export it to PDF."
+# ================================================================
+"""
+
+def print_excel_guide() -> None:
+    print(EXCEL_GUIDE.strip())