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:

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"

Related MCP server: NetSuite MCP Server

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

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

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

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

SuiteQL

Saved Searches

Reports

Metadata

Interactive Helpers

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