NS MCP China

Connect any MCP-compatible AI assistant to NetSuite ERP in under 2 minutes.

One command opens a web form. Fill in 3 fields. Click connect. Done.

┌─────────────────────────────────────────────────────┐
│                   WorkBuddy / Claude / Cursor        │
│                          │ stdio                     │
│                          ▼                           │
│              ns-mcp-connector.js                     │
│                   │           │                      │
│    Token auto-refresh     JSON-RPC proxy             │
│          (refresh_token)        │                    │
│                                 ▼                     │
│          NetSuite Official MCP Endpoint              │
│   https://{account}.suitetalk.api.netsuite.com       │
│              /services/mcp/v1/all                    │
└─────────────────────────────────────────────────────┘

Quick Start

1. Clone & Setup

git clone https://github.com/letian940-prog/ns-mcp-china.git
cd ns-mcp-china
node bin/ns-mcp-connector.js --setup

Your browser opens automatically:

Field	What to enter
服务端点 URL	https://YOUR_ACCOUNT_ID.suitetalk.api.netsuite.com/services/mcp/v1/all
客户端 ID	Your OAuth 2.0 Client ID
客户端密钥	Your OAuth 2.0 Client Secret

Click "连接" → NetSuite authorization page opens → Click "Authorize" → Done.

The connector automatically:

• Completes OAuth 2.0 Authorization Code + PKCE flow
• Saves tokens to ~/.ns-mcp/tokens.json
• Updates ~/.workbuddy/mcp.json (if WorkBuddy is installed)

2. Restart Your AI Assistant

Cmd+Q to fully quit, then reopen. Go to Connectors → Custom Connectors → Trust.

3. Start Asking

"查询 NetSuite 的所有 subsidiary"

"Create a customer named Acme Corp with email info@acme.com"

"Run the trial balance report for January 2026"

---

Prerequisites

Node.js >= 18

The connector uses only built-in modules — no npm install needed.

node --version  # Must be >= 18.0.0

NetSuite Configuration

Complete these steps in your NetSuite account before running setup:

Step 1: Enable OAuth 2.0

Setup > Company > Enable Features > SuiteCloud → Check OAuth 2.0

Step 2: Create an Integration

Setup > Integration > Manage Integrations > New

Field	Value
Name	MCP Server (or any name)
Authorization Code Grant	Check
Public Client	Check
Audience	NetSuite Service Endpoint Runtime
Scopes	NetSuite AI Connector Service
Redirect URI	http://127.0.0.1:38271/callback
Token Lifetime	3600 (default, or longer)

Save and copy the Client ID and Client Secret (shown once).

Important: Check "Public Client" — if unchecked, NetSuite rejects the PKCE flow.

Step 3: Install MCP Standard Tools SuiteApp

Customization > SuiteBundler > Search & Install Bundles → Search MCP Standard Tools → Install

Without this bundle, the MCP endpoint returns 0 tools.

Step 4: Create a Non-Admin Role

Oracle's official FAQ states: "Administrator role does not work for AI Connector Service."

Setup > Users/Roles > Manage Roles > New

Add these permissions:

• Setup > MCP Server Connection (Full)
• Setup > Log in using OAuth 2.0 Access Tokens (Full)
• Setup > REST Web Services (Full)

Assign this role to a user, and use that user to authorize during setup.

---

How It Works

Two Modes, One File

Mode	Command	Purpose
Setup	node bin/ns-mcp-connector.js --setup	Web UI for first-time configuration
Proxy	node bin/ns-mcp-connector.js (called by AI assistant)	Forwards MCP messages + manages tokens

Token Lifecycle

access_token (60min) ──expires──> refresh_token ──auto──> new access_token
                                        │
                                   expires too
                                        │
                                        ▼
                              Connector opens browser
                              for re-authorization

• Access token: Stored in ~/.ns-mcp/tokens.json, auto-refreshed before expiry
• Refresh token: Used to silently renew access tokens
• Full re-auth: If both expire, connector automatically opens browser

Security

• Tokens stored in ~/.ns-mcp/tokens.json with permission 600
• mcp.json contains no credentials — only a path to the connector script
• All OAuth traffic goes through localhost callback (port 38271)
• Zero external dependencies — no supply chain risk

---

Configuration

WorkBuddy

After running --setup, the connector automatically updates ~/.workbuddy/mcp.json:

{
  "mcpServers": {
    "ns-mcp-china": {
      "command": "node",
      "args": ["/path/to/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {},
      "description": "NetSuite MCP (auto-managed token)"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ns-mcp-china": {
      "command": "node",
      "args": ["/path/to/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {
        "NETSUITE_MCP_URL": "https://YOUR_ACCOUNT_ID.suitetalk.api.netsuite.com/services/mcp/v1/all",
        "NETSUITE_CLIENT_ID": "YOUR_CLIENT_ID",
        "NETSUITE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ns-mcp-china": {
      "command": "node",
      "args": ["/path/to/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {
        "NETSUITE_MCP_URL": "https://YOUR_ACCOUNT_ID.suitetalk.api.netsuite.com/services/mcp/v1/all",
        "NETSUITE_CLIENT_ID": "YOUR_CLIENT_ID",
        "NETSUITE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

When env variables are set, the connector can auto-trigger OAuth on first run without --setup.

Environment Variables

Variable	Required	Description
NETSUITE_MCP_URL	No	Full MCP endpoint URL (account ID extracted from this)
NETSUITE_CLIENT_ID	No	OAuth 2.0 Client ID (enables auto-OAuth)
NETSUITE_CLIENT_SECRET	No	OAuth 2.0 Client Secret

If env variables are omitted, the connector relies on tokens saved by --setup.

---

Available Tools (17)

The connector forwards all MCP calls to NetSuite's official MCP endpoint, which provides:

Record Operations

Tool	Description
ns_createRecord	Create a new record (customer, salesOrder, invoice, etc.)
ns_getRecord	Retrieve a record by internal ID
ns_updateRecord	Update fields on an existing record

SuiteQL

Tool	Description
ns_runCustomSuiteQL	Execute a custom SuiteQL query with pagination
ns_getSuiteQLMetadata	Discover available tables and column definitions

Saved Searches

Tool	Description
ns_listSavedSearches	List saved searches, optionally filtered by record type
ns_runSavedSearch	Execute a saved search by ID

Reports

Tool	Description
ns_listAllReports	List all available financial and operational reports
ns_runReport	Run a report (trial balance, P&L, AR/AP aging, etc.)
ns_report_filters_app	Get available filter options for reports

Metadata

Tool	Description
ns_getRecordTypeMetadata	Get field definitions and sublists for a record type
ns_getSubsidiaries	List all subsidiaries with currencies and hierarchy
ns_getAccountingBooks	List accounting books (primary and secondary)
ns_getAccountingContexts	List accounting contexts for multi-currency
ns_getNexusIds	List tax nexus records by country

Interactive Helpers

Tool	Description
ns_prompt_library_app	Browse pre-built prompt templates
ns_selector_app	Discover valid record types and their key fields

---

Troubleshooting

Browser shows page_not_found.jsp

Cause: OAuth 2.0 not enabled, or Integration type is wrong.

Fix:

1. Setup > Company > Enable Features > SuiteCloud → Enable OAuth 2.0
2. Verify Integration has "Authorization Code Grant" checked (not just Client Credentials)
3. Verify "Public Client" is checked

redirect_uri_mismatch error

Cause: Redirect URI in NetSuite doesn't match.

Fix: Ensure Redirect URI is exactly http://127.0.0.1:38271/callback

Port 38271 already in use

lsof -i :38271
kill -9 <PID>

0 tools returned after connection

Cause: MCP Standard Tools SuiteApp not installed.

Fix: Customization > SuiteBundler > Search & Install Bundles → Install "MCP Standard Tools"

Authorization succeeds but API calls return 401

Cause: Used Administrator role for authorization.

Fix: Create a non-admin role with MCP Server Connection + OAuth 2.0 Access Tokens + REST Web Services permissions. Re-run --setup and authorize as that user.

Token expired and not refreshing

rm ~/.ns-mcp/tokens.json
node bin/ns-mcp-connector.js --setup

---

Development

npm install      # Install TypeScript deps (for src/ legacy server)
npm run build    # Compile TypeScript
npm run dev      # Watch mode

The connector (bin/ns-mcp-connector.js) is plain JavaScript with zero dependencies — it can be edited and run directly without compilation.

Project Structure

ns-mcp-china/
├── bin/
│   └── ns-mcp-connector.js       # Main connector (zero deps)
├── src/                           # Legacy stdio MCP server (TypeScript)
│   ├── index.ts
│   ├── netsuite-client.ts
│   └── tools/
│       ├── records.ts
│       ├── suiteql.ts
│       ├── searches.ts
│       ├── reports.ts
│       ├── metadata.ts
│       └── apps.ts
├── server.json                    # MCP Registry description
├── package.json
├── tsconfig.json
├── .env.example
├── LICENSE
└── README.md

License

MIT