{"id":50012728,"url":"https://github.com/maximizegpt/netsuite-saved-search-mcp","last_synced_at":"2026-05-23T20:01:04.848Z","repository":{"id":358975901,"uuid":"1243919133","full_name":"maximizeGPT/netsuite-saved-search-mcp","owner":"maximizeGPT","description":"MCP server exposing NetSuite saved search exports as a structured query interface for Claude","archived":false,"fork":false,"pushed_at":"2026-05-19T23:16:47.000Z","size":130,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T00:13:40.069Z","etag":null,"topics":["claude","finance","mcp","model-context-protocol","netsuite","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximizeGPT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T19:46:36.000Z","updated_at":"2026-05-19T23:08:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximizeGPT/netsuite-saved-search-mcp","commit_stats":null,"previous_names":["maximizegpt/netsuite-saved-search-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maximizeGPT/netsuite-saved-search-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fnetsuite-saved-search-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fnetsuite-saved-search-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fnetsuite-saved-search-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fnetsuite-saved-search-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximizeGPT","download_url":"https://codeload.github.com/maximizeGPT/netsuite-saved-search-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fnetsuite-saved-search-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33410345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","finance","mcp","model-context-protocol","netsuite","python"],"created_at":"2026-05-20T01:08:27.259Z","updated_at":"2026-05-23T20:01:04.835Z","avatar_url":"https://github.com/maximizeGPT.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# netsuite-saved-search-mcp\n\n[![CI](https://github.com/maximizeGPT/netsuite-saved-search-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/maximizeGPT/netsuite-saved-search-mcp/actions/workflows/ci.yml)\n[![PyPI version](https://badge.fury.io/py/netsuite-saved-search-mcp.svg)](https://pypi.org/project/netsuite-saved-search-mcp/)\n[![Release](https://img.shields.io/github/v/release/maximizeGPT/netsuite-saved-search-mcp?include_prereleases\u0026sort=semver)](https://github.com/maximizeGPT/netsuite-saved-search-mcp/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n\nNetSuite saved search exports look like Excel files but are actually XML SpreadsheetML with a .xls extension — Excel opens them, pandas trips on them, and most teams writing Claude integrations against NetSuite end up rebuilding the same parser by hand. This MCP server exposes those exports as a structured query interface for Claude: discover files, inspect columns, filter and aggregate rows, categorize by memo keywords, surface anomalies. Seven tools wrap a parser that handles the format's real quirks — entity-encoded text, empty cells flagged with `ss:Index`, drifting column layouts between saved searches, DateTime cells that won't parse. The parser runs in lxml's recovery mode and reports broken cells as structured warnings rather than crashing on them.\n\n## What an auditable agent run looks like\n\nA condensed exchange reproduced from the [`claude-eval-harness`](https://github.com/maximizeGPT/claude-eval-harness)\nNetSuite suite's `anomaly_zero_activity_june` case (`runs/baseline-sonnet-4-6.json`).\nThe agent's tool calls are auditable, the parser's `total_supporting_count`\nis citable, and the model never has to fabricate numbers it can't point at.\n\n```\nuser      What stands out in this GL? Run detect_anomalies on\n          sample_gl_export.xls (account_column=Account,\n          amount_column=Amount, period_column=Period).\n\nagent     → detect_anomalies(file_path=\"sample_gl_export.xls\",\n                             account_column=\"Account\",\n                             amount_column=\"Amount\",\n                             period_column=\"Period\")\n          ← {findings: [\n              {severity:\"HIGH\", category:\"zero_activity_period\",\n               description:\"No rows recorded for Jun 2024\",\n               total_supporting_count:0},\n              {severity:\"MEDIUM\", category:\"ratio_anomaly\",\n               description:\"Account 1200 in Sep 2024 totals 319,219.74\n                            — 3.1x the 1200 median of 103,259.01\",\n               supporting_rows:[...10 rows...],\n               total_supporting_count:17}]}\n\nagent     HIGH: no rows posted to June 2024 inside an otherwise continuous\n          range — likely an extraction gap or skipped close. MEDIUM:\n          Account 1200 spiked to 3.1× its own median in September across\n          17 cited rows. supporting_rows trims to 10; total_supporting_count\n          carries the full count so it's verifiable.\n```\n\nThe full anomaly response also lives in [`examples/walkthrough.md`](examples/walkthrough.md).\n\n## Quick start\n\n```bash\nuvx netsuite-saved-search-mcp           # or: pip install netsuite-saved-search-mcp\nexport NSMCP_ROOT=/path/to/your/exports\n```\n\nAdd to Claude Desktop's config (full version in [examples/claude_desktop_config.json](examples/claude_desktop_config.json)):\n\n```json\n{\n  \"mcpServers\": {\n    \"netsuite-saved-search\": {\n      \"command\": \"uvx\",\n      \"args\": [\"netsuite-saved-search-mcp\"],\n      \"env\": {\"NSMCP_ROOT\": \"/path/to/your/exports\"}\n    }\n  }\n}\n```\n\nThen any tool call lands directly:\n\n```json\n{\n  \"tool\": \"query_export\",\n  \"arguments\": {\n    \"file_path\": \"Q3_GL.xls\",\n    \"filters\": [{\"op\": \"eq\", \"column\": \"Account\", \"value\": \"4000\"}]\n  }\n}\n```\n\n## Standalone Python usage\n\nThe parser is usable directly without the MCP transport — useful for notebooks, batch scripts, or pytest fixtures that don't want stdio in the loop:\n\n```python\nfrom netsuite_saved_search_mcp.parser import NetSuiteExport\n\nexport = NetSuiteExport(\"tests/fixtures/sample_gl_export.xls\")\nprint(export.headers)            # ['Order Type', 'Date', 'Period', ...]\nprint(len(export.rows))          # 212\nprint(export.rows[0][\"Account\"]) # '4000'\n```\n\n`NetSuiteExport(path)` parses the file end-to-end on construction. `.rows` is a list of dicts keyed by header name; cell values are typed (`str`, `int`, `float`, `datetime.date`, `bool`, or `None`). `.parse_warnings` exposes any recoverable issues lxml hit on the way through.\n\n## Security boundary\n\nFor audit and accounting use, the server enforces a tight blast radius on what it can touch. (Reporting channel for vulnerabilities is in [`SECURITY.md`](SECURITY.md).)\n\n- **All reads constrained under `NSMCP_ROOT`.** Every tool resolves its file-path argument relative to this env var (or `os.getcwd()` if unset). Paths that resolve outside the root raise `PathTraversalError` before any I/O.\n- **Symlink-escape blocked via realpath comparison.** [`_resolve_under_root`](src/netsuite_saved_search_mcp/tools.py#L59) calls `Path.resolve()` on the candidate then checks `relative_to(root)`. `resolve()` collapses `..` segments and follows symlinks to their real target, so a symlink inside the root that points outside it fails the check.\n- **No writes.** The parser opens `.xls` files for reading only. No tool writes to the filesystem.\n- **No network calls.** Runtime dependencies are `mcp`, `lxml`, `python-dateutil`, `pydantic` — none of them dial out during a tool call.\n- **Stderr logs are scoped.** Startup logs the `NSMCP_ROOT` path. Tool calls log nothing by default; row data, column values, and financial figures never reach the log handler.\n\n## Why this exists\n\nNetSuite saved search exports use XML SpreadsheetML, not Excel binary, despite the .xls extension. Column layouts drift between saved searches, so code that hardcodes column letters breaks on the next export. Empty cells are silently omitted from each row with `ss:Index` attributes marking where they were, which trips naive sequential parsers. Every finance team using Claude with NetSuite ends up rebuilding the same parser. This server solves it once.\n\n## Tools\n\n| Tool | Description | Key parameters |\n|---|---|---|\n| `list_exports` | Scan a directory for .xls files; return one summary per file with row counts, header counts, warning counts, and detected date range. | `directory` |\n| `get_headers` | Return column headers, their spreadsheet column letters, and the 0-indexed header row. | `file_path` |\n| `query_export` | Filter rows by a list of predicates (AND-combined), optionally project to a subset of columns, cap results. | `file_path, filters, columns?, limit?` |\n| `aggregate_export` | Group rows by one or more columns; compute sum/count/avg/min/max per group. | `file_path, group_by, measures` |\n| `categorize_by_memo` | Tag every row with a `_category` derived from case-insensitive keyword rules across one or more memo columns. | `file_path, memo_columns, rules` |\n| `detect_anomalies` | Three checks: zero-activity periods (HIGH), ratio anomalies (MEDIUM), document-count variance (MEDIUM). | `file_path, account_column, amount_column, period_column` |\n| `get_parse_warnings` | Return parse warnings (phantom_column, bad_datetime, encoding_recovery, empty_row_skipped) captured during parsing of the specified file. | `file_path` |\n\nPredicates are a discriminated union keyed on `op`. Example query with two predicates:\n\n```json\n{\n  \"file_path\": \"deferred_commissions_2024.xls\",\n  \"filters\": [\n    {\"op\": \"eq\", \"column\": \"Account\", \"value\": \"1321\"},\n    {\"op\": \"date_range\", \"column\": \"Date\", \"start\": \"2024-01-01\", \"end\": \"2024-12-31\"}\n  ],\n  \"columns\": [\"Date\", \"Document Number\", \"Amount\", \"Memo (line)\"],\n  \"limit\": 100\n}\n```\n\nMeasures for `aggregate_export`:\n\n```json\n[{\"column\": \"Amount\", \"op\": \"sum\", \"alias\": \"total\"}, {\"column\": \"Document Number\", \"op\": \"count\"}]\n```\n\n## Example walkthrough\n\nSee [examples/walkthrough.md](examples/walkthrough.md) for an end-to-end example using the included sanitized fixtures.\n\n## Limitations\n\n- Only handles saved search exports, not raw transaction-level XML from SuiteScript or RESTlets.\n- All-string exports with no typed columns may misidentify the header row; an explicit `header_row` override is planned.\n- Memo categorization uses case-insensitive substring matching against US-English keywords. No stemming, no fuzzy matching.\n- `detect_anomalies` only recognises period labels in three formats — `Jan 2024`, `January 2024`, `2024-01`. Quarter labels (`Q1 2024`) and fiscal-period labels are silently skipped. The ratio and document-count checks also need ≥3 distinct periods to produce a finding.\n- Not optimized for exports larger than 100k rows. The cache holds parsed `NetSuiteExport` instances in memory keyed by `(path, mtime)` and is unbounded — a long-running session against a large directory will keep every parsed export resident.\n- Coverage tested against three synthesized fixtures that exercise typed cells, lxml recovery, and 14-row-metadata header detection. Real-world saved searches with column layouts beyond those shapes may surface gaps.\n- v0.1. The MCP tool schemas and the parser's `Predicate`/`Measure` models may change before v1.0.\n\n## Contributing\n\nIssues and PRs welcome. Run `uv run pytest`, `uv run mypy src`, and `uv run ruff check src tests` before submitting; all three should be clean. Commits follow [Conventional Commits](https://www.conventionalcommits.org/). New tools require a Pydantic response model, a happy-path test against the included GL fixture, a failure-path test (missing file or unknown column), and an entry in the table above.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fnetsuite-saved-search-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximizegpt%2Fnetsuite-saved-search-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fnetsuite-saved-search-mcp/lists"}