NetSuite MCP Server OAuth 2.0 SuiteQL API Access

Overview

This MCP (Model Context Protocol) server provides a secure intermediary between large language models (LLMs) or other AI agents and a NetSuite account. It exposes a small, focused API that uses OAuth 2.0 to obtain and manage NetSuite access tokens, then runs SuiteQL queries, saved searches, reports, and REST API calls on behalf of the caller. By centralizing authentication and access logic, the server reduces credential sprawl and lets LLM-driven tools request data using natural language or structured queries.

For developers building AI integrations, the server is useful because it standardizes how downstream models access NetSuite data and enforces security best practices (scoped OAuth credentials, token caching, HTTPS). It also translates simple requests into NetSuite SuiteQL or REST calls, making it straightforward to combine NetSuite data sources with generative models (for chat assistants, automation bots, or analytics).

Features

• OAuth 2.0 client handling for NetSuite (token acquisition and refresh)
• SuiteQL execution endpoint for SQL-style queries against NetSuite records
• Proxy endpoints for saved searches, standard reports, and REST API calls
• Simple JSON-based API suitable for MCP / LLM tool integrations
• Token caching and configurable timeouts to reduce auth overhead
• Configurable access controls and CORS for safe hosting
• Docker-friendly configuration for deployment

Installation / Configuration

Prerequisites: Node.js (14+), npm or Docker.

1. Clone the repository and install dependencies:

git clone https://github.com/dsvantien/netsuite-mcp-server.git
cd netsuite-mcp-server
npm install

2. Create a .env file (example variables shown):

# NetSuite OAuth2
NETSUITE_ACCOUNT=1234567_SB1
NETSUITE_CLIENT_ID=your_client_id
NETSUITE_CLIENT_SECRET=your_client_secret
NETSUITE_OAUTH_TOKEN_URL=https://account.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token

# Server
PORT=3000
NODE_ENV=production
CACHE_TTL_SECONDS=300

# Security
ALLOWED_ORIGINS=https://your-app.example.com

3. Run locally:

npm run build   # if TypeScript or build step exists
npm start
# or for development:
npm run dev

4. Docker (optional) — build and run:

# Dockerfile (example)
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV NODE_ENV=production
CMD ["node", "dist/index.js"]

docker build -t netsuite-mcp-server .
docker run -p 3000:3000 --env-file .env netsuite-mcp-server

Available Resources

Below are typical endpoints the server exposes (paths may vary by implementation). Check the repository for exact route names and payload shapes.

Example SuiteQL request (curl):

curl -X POST https://mcp.example.com/suiteql \
  -H "Authorization: Bearer <mcp-api-key-or-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT id, entityid FROM customer WHERE isinactive = \'F\' LIMIT 10;"}'

Response (JSON):

{
  "columns": ["id", "entityid"],
  "rows": [
    [123, "Acme Corp"],
    [124, "Beta LLC"]
  ]
}

Use Cases

• Natural language assistant: Connect an LLM that accepts a “tool” for NetSuite data. The assistant sends plain-language requests (e.g., “List top 10 customers by revenue this quarter”), which your application translates to SuiteQL and executes via the MCP server.
• Report automation: Trigger scheduled jobs that run saved reports or SuiteQL queries and push summarized results to Slack, email, or a BI tool.
• Data enrichment: Combine NetSuite contact or transaction data with external sources. Use the MCP server to fetch records securely, then enrich them in your application before sending to a model for analysis.
• Restricted service accounts: Host one server that holds OAuth client credentials and enforces scoping/filters, so individual clients never need direct NetSuite credentials.

Security & Best Practices

• Store NETSUITE_CLIENT_SECRET and other secrets in a secure vault or environment variables; do not commit them to source control.
• Serve the MCP server over HTTPS and restrict ALLOWED_ORIGINS to known hosts.
• Use least-privilege OAuth scopes on the NetSuite application credentials.
• Audit and log calls to the proxy endpoints; consider rate limiting and IP allowlists.
• Validate and sanitize SuiteQL and request payloads to prevent abuse.

For full API details and code examples, refer to the repository code and example configuration files. The server is intended to be extended or embedded into larger LLM orchestration systems that use MCP-style tooling to provide secure, auditable access to NetSuite data.