NetSuite SuiteAnalytics ODBC MCP

A local, read-only Model Context Protocol (MCP) server for querying a user's own NetSuite SuiteAnalytics Connect account through the user's locally installed ODBC driver.

This project is an independent community project. It is not affiliated with, sponsored by, or endorsed by Oracle or NetSuite. NetSuite and SuiteAnalytics Connect are trademarks or products of Oracle.

Use this software only with accounts, data, credentials, roles, services, and driver software that you are authorized and licensed to use. Configure a dedicated least-privilege NetSuite role. This project does not grant a NetSuite subscription, SuiteAnalytics Connect entitlement, driver license, or right to access any data.

What It Does

The server exposes exactly four MCP tools:

Tool	Purpose
netsuite_query	Execute one bounded, read-only SELECT or WITH query.
netsuite_tables	Search bounded ODBC table metadata visible to the configured role.
netsuite_describe	Describe columns for one exact table visible to the configured role.
netsuite_status	Return secret-safe status and optionally perform a live connection check.

The MCP client launches this package as a local child process and communicates over standard input/output. The Node.js process uses the system ODBC driver manager and the user's named local data source (DSN) to connect directly to NetSuite. There is no HTTP listener, remote transport, or hosted service.

The proprietary NetSuite ODBC driver and installer are never bundled, uploaded, downloaded, mirrored, or licensed by this package. Each user must obtain the driver independently from an authorized NetSuite account, accept the applicable terms, and install and configure it locally. Java, JDBC, and NQjc.jar are not required.

Requirements

• Node.js 20 or later.
• A supported local environment for the native Node odbc addon. Native binaries are platform-, architecture-, Node ABI-, and driver-manager-specific; installation may require platform build tools.
• A system ODBC driver manager: unixODBC on macOS/Linux, or the Windows ODBC Data Source Administrator on Windows.
• SuiteAnalytics Connect enabled and licensed for the user's NetSuite account.
• The latest ODBC driver available from the user's authorized account. Actual compatibility with the selected OS, architecture, Node runtime, driver manager, NetSuite release, and account must be tested locally.
• A local system or user DSN whose name exactly matches NETSUITE_ODBC_DSN.
• A dedicated least-privilege role with Connect access and only the record permissions needed for the intended use.
• A TBA integration and access token assigned to the intended user and that exact role.
• Outbound DNS and network access to the account-specific Connect service host on port 1708.

ODBC access does not expose every NetSuite record, field, feature, saved search, workbook, SuiteScript API, REST record, or SuiteQL surface. The NetSuite2.com Connect schema and the configured role determine what is available.

Quick Start

1. In an authorized NetSuite account, go to Settings > Set Up SuiteAnalytics Connect.
2. Choose the correct operating system, record the values under Your Configuration, accept the applicable terms, then download, extract, and install the ODBC driver locally.
3. Configure a system or user DSN using the installed driver and the recorded NetSuite configuration. Set NETSUITE_ODBC_DSN to that DSN's exact name.
4. Create a dedicated least-privilege role, TBA integration, and token as described in Token-based authentication.
5. Run the exact public package version without a global installation:

npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 doctor

For development from a source checkout, use npm install followed by npm run build.

6. Supply the required environment through the MCP launcher's protected configuration. These are placeholders, not working values:

NETSUITE_ACCOUNT_ID=YOUR_ACCOUNT_ID
NETSUITE_ROLE_ID=YOUR_NUMERIC_ROLE_ID
NETSUITE_SERVICE_HOST=YOUR_SERVICE_HOST_FROM_NETSUITE
NETSUITE_ODBC_DSN=YOUR_LOCALLY_CONFIGURED_NETSUITE_DSN
NETSUITE_CONSUMER_KEY=YOUR_CONSUMER_KEY
NETSUITE_CONSUMER_SECRET=YOUR_CONSUMER_SECRET
NETSUITE_TOKEN_ID=YOUR_TOKEN_ID
NETSUITE_TOKEN_SECRET=YOUR_TOKEN_SECRET

7. Run local diagnostics, then deliberately run the live test when authorized:

node dist/cli.js doctor
node dist/cli.js test-connection

doctor is local-only with respect to NetSuite: it validates configuration, loads the native ODBC addon/driver manager, and performs a DNS lookup, but does not open the DSN, authenticate, or query NetSuite. test-connection is live: it opens the configured DSN with TBA and executes SELECT 1, which may create NetSuite audit or connection records.

8. Configure the MCP client to launch the exact package version in stdio mode:

{
  "mcpServers": {
    "netsuite": {
      "command": "npx",
      "args": ["-y", "netsuite-suiteanalytics-odbc-mcp@1.0.0", "serve"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "NETSUITE_ROLE_ID": "YOUR_NUMERIC_ROLE_ID",
        "NETSUITE_SERVICE_HOST": "YOUR_SERVICE_HOST_FROM_NETSUITE",
        "NETSUITE_ODBC_DSN": "YOUR_LOCALLY_CONFIGURED_NETSUITE_DSN",
        "NETSUITE_CONSUMER_KEY": "YOUR_CONSUMER_KEY",
        "NETSUITE_CONSUMER_SECRET": "YOUR_CONSUMER_SECRET",
        "NETSUITE_TOKEN_ID": "YOUR_TOKEN_ID",
        "NETSUITE_TOKEN_SECRET": "YOUR_TOKEN_SECRET"
      }
    }
  }
}

Client configuration formats vary. Protect the child-process environment. Do not pass credentials as CLI arguments; the CLI rejects configuration arguments. A tool caller cannot choose a DSN, connection string, account, role, or credentials. All four tools use the single operator-configured NETSUITE_ODBC_DSN and environment.

LibreChat Setup

The package is published as netsuite-suiteanalytics-odbc-mcp@1.0.0. LibreChat runs it as a local stdio MCP process.

The LibreChat backend must run in the same environment that has Node.js 20+, the ODBC driver manager, the authorized NetSuite ODBC driver, and the configured DSN. For Docker deployments, those dependencies and the DSN must exist inside the LibreChat backend container; installing them only on the Docker host is not enough. Do not put the proprietary driver or credentials in a public image.

Set these values in LibreChat's protected server-side environment, not directly in source-controlled librechat.yaml:

NETSUITE_ACCOUNT_ID=YOUR_ACCOUNT_ID
NETSUITE_ROLE_ID=YOUR_NUMERIC_ROLE_ID
NETSUITE_SERVICE_HOST=YOUR_SERVICE_HOST_FROM_NETSUITE
NETSUITE_ODBC_DSN=YOUR_LOCALLY_CONFIGURED_NETSUITE_DSN
NETSUITE_CONSUMER_KEY=YOUR_CONSUMER_KEY
NETSUITE_CONSUMER_SECRET=YOUR_CONSUMER_SECRET
NETSUITE_TOKEN_ID=YOUR_TOKEN_ID
NETSUITE_TOKEN_SECRET=YOUR_TOKEN_SECRET

Add this entry to librechat.yaml:

mcpServers:
  netsuite-suiteanalytics:
    title: NetSuite SuiteAnalytics
    description: Bounded read-only access to the configured SuiteAnalytics Connect role
    type: stdio
    command: npx
    args:
      - -y
      - netsuite-suiteanalytics-odbc-mcp@1.0.0
      - serve
    env:
      NETSUITE_ACCOUNT_ID: '${NETSUITE_ACCOUNT_ID}'
      NETSUITE_ROLE_ID: '${NETSUITE_ROLE_ID}'
      NETSUITE_SERVICE_HOST: '${NETSUITE_SERVICE_HOST}'
      NETSUITE_ODBC_DSN: '${NETSUITE_ODBC_DSN}'
      NETSUITE_CONSUMER_KEY: '${NETSUITE_CONSUMER_KEY}'
      NETSUITE_CONSUMER_SECRET: '${NETSUITE_CONSUMER_SECRET}'
      NETSUITE_TOKEN_ID: '${NETSUITE_TOKEN_ID}'
      NETSUITE_TOKEN_SECRET: '${NETSUITE_TOKEN_SECRET}'
      NETSUITE_SERVICE_PORT: '1708'
      NETSUITE_DATA_SOURCE: NetSuite2.com
      NETSUITE_TELEMETRY: 'off'
    initTimeout: 30000
    timeout: 130000
    stderr: inherit
    serverInstructions: true
    chatMenu: false

Before starting LibreChat, validate the setup from the same host or container and operating-system user that runs the LibreChat backend:

npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 doctor
npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 test-connection

test-connection makes a live TBA connection and executes SELECT 1. Restart LibreChat after changing librechat.yaml. In the Agent Builder, select Add MCP Server Tools, choose NetSuite SuiteAnalytics, and enable only the required tools. chatMenu: false keeps the tools agent-only; enable it only after reviewing access controls and data exposure.

This local MVP uses one process-level NetSuite credential set and does not provide per-user OAuth or tenant isolation. Do not expose one shared NetSuite account to unrelated LibreChat users. Query results can enter LibreChat history and model-provider requests, so review user access, retention, tracing, backups, sharing, and model-provider approval before enabling the server.

See the full LibreChat guide and setup guide for deployment details, limits, and security boundaries.

Safety Model

• Only one SELECT statement or read-only WITH query is accepted.
• SQL comments, semicolons, write/DDL/control keywords, and unsupported or ambiguous syntax are rejected locally.
• Row count, serialized row bytes, timeout, pool size, concurrency, and physical connection lifetime are bounded. Native driver buffers may allocate beyond the serialized response cap.
• Optional table allowlists and denylists narrow local access.
• The configured NetSuite role is the authoritative access boundary. Local SQL checks are defense in depth, not a substitute for least privilege.
• A fresh Connect token password is generated only when a new physical ODBC connection is created. Pooled operations reuse that connection until it expires or closes.
• Three consecutive classified authentication failures open a local circuit breaker for a configurable cooldown.
• Project telemetry is fixed to off. NetSuite, the ODBC driver, the MCP client, the selected model provider, the operating system, and dependencies may have their own logging or telemetry.
• Errors are categorized and redacted before being returned, but logs, queries, results, and MCP transcripts must still be treated as potentially sensitive.

CLI

npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 serve
npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 doctor
npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 test-connection
npx -y netsuite-suiteanalytics-odbc-mcp@1.0.0 print-example-config

serve is the default. Pin an exact version rather than relying on the npm latest tag. With a source build, substitute node dist/cli.js for the npx command. Standard output carries MCP protocol messages while serving; do not wrap the process with software that writes banners or logs to stdout.

Scope

This release supports one local, single-user stdio process. It does not provide HTTP or another remote transport, a hosted service, multi-user tenancy, writes, DDL, SuiteScript, REST access, credential hosting, driver acquisition, driver redistribution, automatic NetSuite role provisioning, or arbitrary SQL compatibility.

Kiokii-originated queries may require changes for the SuiteAnalytics Connect ODBC SQL dialect, NetSuite2.com schema, identifier quoting, functions, joins, date handling, and pagination. Use netsuite_tables and netsuite_describe against the target account rather than assuming another connection method's schema or SQL is compatible. No Kiokii-specific schema, customization, adapter, or support guarantee is included.

Documentation

• Installation and configuration
• LibreChat integration
• Maintainer publishing guide
• Token-based authentication
• Troubleshooting
• Security, privacy, and responsibilities
• Licensing and third-party software
• Vulnerability reporting

License

The original project code and documentation are licensed under Apache License 2.0. The NetSuite service, ODBC driver, and installer are separate proprietary products governed by their owners' terms. See LICENSE, NOTICE, and licensing guidance. This repository does not provide legal advice.