NetSuite MCP for WorkBuddy

让 AI 助手直接操作你的 NetSuite ERP

中文 · English

中文

这是什么？

NetSuite MCP for WorkBuddy 是一个连接器工具，让你的 AI 助手（如 WorkBuddy、Claude、Cursor）能够直接查询和操作 NetSuite ERP 系统——创建客户、跑报表、查数据，全部用自然语言完成。

你只需要做三件事：

1. 在 NetSuite 后台做一次集成配置（约 10 分钟）

2. 下载本工具并运行一条命令（约 1 分钟）

3. 在浏览器里填 3 个框、点一下授权（约 30 秒）

之后就可以对 AI 说"查询所有 subsidiary"、"跑一下试算平衡表"等，AI 会自动调用 NetSuite 的 17 个工具完成任务。

它是怎么工作的？

你 → AI 助手（WorkBuddy/Claude/Cursor）
         │
         ▼
    本连接器（自动管理 Token）
         │
         ▼
    NetSuite 官方 MCP 服务
    （17 个工具：记录操作、SuiteQL、报表等）

核心优势：

• 零依赖：纯 Node.js 内置模块，不需要 npm install

• 自动刷新 Token：Token 过期自动续期，无需人工干预

• 安全：凭据存储在本地文件（权限 600），不泄露到配置文件

• 一键配置：浏览器填 3 个框，OAuth 授权全自动

Related MCP server: NetSuite MCP Server

完整安装指南（手把手，按顺序操作）

第一步：在 NetSuite 后台配置集成授权

这一步在你的 NetSuite 网页后台操作，需要管理员权限。 预计耗时：10 分钟

1.1 启用 OAuth 2.0 功能

1. 登录 NetSuite → 顶部菜单 Setup > Company > Enable Features

2. 点击 SuiteCloud 标签页

3. 找到 OAuth 2.0，勾选它

4. 点击 Save

如果已经勾选了，跳过这步。

1.2 创建集成（Integration）

1. 顶部菜单 Setup > Integration > Manage Integrations > New

2. 按下表填写：

3. 点击 Save

4. 立刻复制 Client ID 和 Client Secret（关闭页面后看不到了！）

⚠️ 两个必须勾的选项：Authorization Code Grant 和 Public Client，缺任何一个都会导致连接失败。

1.3 安装 MCP Standard Tools 套件

1. 顶部菜单 Customization > SuiteBundler > Search & Install Bundles

2. 搜索 MCP Standard Tools

3. 点击 Install，等待安装完成

不装这个套件，连接成功但 0 个工具可用。

1.4 创建专用角色（不能用管理员！）

Oracle 官方文档明确说明：管理员角色不能用于 AI Connector Service。

1. 顶部菜单 Setup > Users/Roles > Manage Roles > New

2. 角色名称填 MCP User（或任意名称）

3. 在 Permissions 标签页添加以下权限：

4. 点击 Save

5. 把这个角色分配给一个用户：Setup > Users/Roles > Assign Access Roles

6. 记住这个用户的登录名和密码——后面授权时要用它登录

✅ 第一步完成！你现在有了：Client ID、Client Secret、一个有权限的非管理员用户。

第二步：下载并安装本工具

预计耗时：1 分钟 前提：电脑上已安装 Node.js 18 或以上版本

2.1 检查 Node.js

打开终端（macOS: Cmd+空格 搜 Terminal），输入：

node --version

如果版本号 >= 18，继续。如果没装或版本太低，去 https://nodejs.org 下载安装。

2.2 下载项目

git clone https://github.com/letian940-prog/ns-mcp-china.git
cd ns-mcp-china

不需要 npm install！这个工具零外部依赖，下载即用。

✅ 第二步完成！项目已经下载到本地。

第三步：运行配置向导，连接 NetSuite

预计耗时：30 秒

在刚才的终端里运行：

node bin/ns-mcp-connector.js --setup

浏览器会自动打开一个配置页面。按以下步骤操作：

1. 在表单中填写 3 个字段：

URL 中的 td3065115 换成你的 NetSuite Account ID。

2. 点击 "连接" 按钮

3. 浏览器跳转到 NetSuite 授权页面

4. 用第一步 1.4 创建的非管理员用户登录

5. 点击 Authorize（授权）

6. 页面跳回本地，显示"连接成功！"

连接器自动完成了以下工作：

• OAuth 2.0 授权流程

• Token 保存到 ~/.ns-mcp/tokens.json（权限 600）

• 更新 ~/.workbuddy/mcp.json 配置文件

✅ 第三步完成！Token 已保存，配置已写入。

第四步：重启 AI 助手并验证

4.1 完全退出 AI 助手

• WorkBuddy：Cmd+Q 完全退出（不是关窗口！），然后重新打开

• Claude Desktop：完全退出后重新打开

• Cursor：重启应用

4.2 信任连接器

进入 设置 → 连接器 → 自定义连接器，找到 netsuite-mcp-workbuddy，点击 Trust。

4.3 测试连接

在 AI 对话里输入：

"查询 NetSuite 的所有 subsidiary"

如果 AI 返回了 NetSuite 的子公司列表，说明连接成功！

✅ 全部完成！以后可以随时用自然语言操作 NetSuite。

常见问题

浏览器打开后显示 page_not_found

原因：OAuth 2.0 功能未启用，或集成类型选错了。

解决：

1. 确认 Setup > Company > Enable Features > SuiteCloud 里已勾选 OAuth 2.0

2. 确认集成里勾选了 Authorization Code Grant（不是 Client Credentials）

3. 确认勾选了 Public Client

报错 redirect_uri_mismatch

原因：集成里的 Redirect URI 和实际不一致。

解决：确认集成里的 Redirect URI 是 http://127.0.0.1:38271/callback，一字不差。

端口 38271 被占用

# 查看谁在占用
lsof -i :38271
# 杀掉占用进程
kill -9 <PID>

然后重新运行 setup。

连接成功但 0 个工具

原因：MCP Standard Tools 套件未安装。

解决：Customization > SuiteBundler > Search & Install Bundles → 搜 MCP Standard Tools → 安装。

授权成功但 API 调用返回 401

原因：用了管理员角色授权。

解决：创建一个非管理员角色（权限：MCP Server Connection + OAuth 2.0 Access Tokens + REST Web Services），用该用户重新运行 --setup。

Token 过期了怎么办？

不用管！ 连接器会用 refresh_token 自动刷新。如果 refresh_token 也过期了，连接器会自动打开浏览器重新授权。

如果实在连不上，可以手动重置：

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

可用的 17 个工具

连接成功后，AI 助手可以调用以下工具：

其他 AI 助手配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "netsuite-mcp-workbuddy": {
      "command": "node",
      "args": ["/你的路径/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {
        "NETSUITE_MCP_URL": "https://你的Account_ID.suitetalk.api.netsuite.com/services/mcp/v1/all",
        "NETSUITE_CLIENT_ID": "你的Client_ID",
        "NETSUITE_CLIENT_SECRET": "你的Client_Secret"
      }
    }
  }
}

Cursor

编辑 .cursor/mcp.json，格式同上。

设置了 env 变量后，连接器会在首次运行时自动触发 OAuth（无需手动跑 --setup）。

技术原理

两种模式，一个文件

Token 生命周期

access_token（60分钟）──到期──> refresh_token ──自动──> 新的 access_token
                                         │
                                    也到期了
                                         │
                                         ▼
                               连接器自动打开浏览器
                               重新授权（你点一下就行）

安全设计

• Token 存在 ~/.ns-mcp/tokens.json，文件权限 600（仅本人可读写）

• mcp.json 里不含任何凭据——只有连接器脚本的路径

• 所有 OAuth 流量走本地 localhost:38271 回调

• 零外部依赖，无供应链风险

项目结构

ns-mcp-china/
├── bin/
│   ├── ns-mcp-connector.js    # 核心连接器（零依赖）
│   └── ns-mcp-setup.js        # 早期 CLI 版本（兼容保留）
├── src/                        # Legacy TypeScript MCP 服务器
│   ├── index.ts
│   ├── netsuite-client.ts
│   └── tools/
├── server.json                 # MCP Registry 描述文件
├── package.json
└── README.md

English

What is this?

NetSuite MCP for WorkBuddy is a connector tool that lets your AI assistant (WorkBuddy, Claude, Cursor) directly query and operate your NetSuite ERP system — create customers, run reports, query data, all in natural language.

You only need to do three things:

1. Configure an integration in your NetSuite backend (~10 min)

2. Download this tool and run one command (~1 min)

3. Fill in 3 fields in a browser and authorize (~30 sec)

After that, you can say to your AI: "List all subsidiaries", "Run the trial balance report", and the AI will automatically call NetSuite's 17 tools.

How does it work?

You → AI Assistant (WorkBuddy/Claude/Cursor)
         │
         ▼
    This Connector (auto-manages Token)
         │
         ▼
    NetSuite Official MCP Service
    (17 tools: record CRUD, SuiteQL, reports, etc.)

Key advantages:

• Zero dependencies: Pure Node.js built-in modules, no npm install needed

• Auto-refreshing tokens: Tokens are renewed automatically, no manual intervention

• Secure: Credentials stored in local file (permission 600), not leaked to config files

• One-click setup: Fill 3 fields in a browser, OAuth authorization is fully automatic

Complete Installation Guide (Step by Step)

Step 1: Configure Integration in NetSuite Backend

This step is done in your NetSuite web backend and requires admin access. Estimated time: 10 minutes

1.1 Enable OAuth 2.0

1. Log in to NetSuite → top menu Setup > Company > Enable Features

2. Click the SuiteCloud tab

3. Find OAuth 2.0 and check it

4. Click Save

Skip this step if already enabled.

1.2 Create an Integration

1. Top menu Setup > Integration > Manage Integrations > New

2. Fill in the form:

3. Click Save

4. Copy the Client ID and Client Secret immediately (they won't be shown again!)

⚠️ Two must-check boxes: Authorization Code Grant and Public Client. Missing either one will cause connection failure.

1.3 Install MCP Standard Tools SuiteApp

1. Top menu Customization > SuiteBundler > Search & Install Bundles

2. Search for MCP Standard Tools

3. Click Install and wait for completion

Without this bundle, the connection succeeds but returns 0 tools.

1.4 Create a Dedicated Role (Cannot use Administrator!)

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

1. Top menu Setup > Users/Roles > Manage Roles > New

2. Role name: MCP User (or any name)

3. In the Permissions tab, add:

4. Click Save

5. Assign this role to a user: Setup > Users/Roles > Assign Access Roles

6. Remember this user's login and password — you'll use it for authorization

✅ Step 1 complete! You now have: Client ID, Client Secret, and a non-admin user with proper permissions.

Step 2: Download and Install This Tool

Estimated time: 1 minute Prerequisite: Node.js 18+ installed on your computer

2.1 Check Node.js

Open Terminal (macOS: Cmd+Space, search "Terminal"), type:

node --version

If the version is >= 18, continue. If not installed or too old, download from https://nodejs.org.

2.2 Clone the project

git clone https://github.com/letian940-prog/ns-mcp-china.git
cd ns-mcp-china

No npm install needed! This tool has zero external dependencies — clone and run.

✅ Step 2 complete! The project is downloaded to your computer.

Step 3: Run the Setup Wizard and Connect to NetSuite

Estimated time: 30 seconds

In the terminal, run:

node bin/ns-mcp-connector.js --setup

Your browser will automatically open a configuration page. Follow these steps:

1. Fill in the 3 fields in the form:

Replace td3065115 in the URL with your NetSuite Account ID.

2. Click the "连接" (Connect) button

3. Browser redirects to NetSuite's authorization page

4. Log in with the non-admin user you created in Step 1.4

5. Click Authorize

6. Page redirects back to localhost, showing "连接成功！" (Connection successful!)

The connector automatically:

• Completes the OAuth 2.0 authorization flow

• Saves tokens to ~/.ns-mcp/tokens.json (permission 600)

• Updates ~/.workbuddy/mcp.json configuration file

✅ Step 3 complete! Tokens saved, configuration written.

Step 4: Restart Your AI Assistant and Verify

4.1 Fully Quit Your AI Assistant

• WorkBuddy: Cmd+Q to fully quit (not just close the window!), then reopen

• Claude Desktop: Fully quit and reopen

• Cursor: Restart the app

4.2 Trust the Connector

Go to Settings → Connectors → Custom Connectors, find netsuite-mcp-workbuddy, click Trust.

4.3 Test the Connection

Type in your AI chat:

"查询 NetSuite 的所有 subsidiary" (List all NetSuite subsidiaries)

If the AI returns a list of subsidiaries from NetSuite, the connection is successful!

✅ All done! You can now operate NetSuite using natural language anytime.

Troubleshooting

Browser shows page_not_found

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

Fix:

1. Verify Setup > Company > Enable Features > SuiteCloud has OAuth 2.0 checked

2. Verify the 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 the Redirect URI is exactly http://127.0.0.1:38271/callback.

Port 38271 already in use

# Find what's using the port
lsof -i :38271
# Kill the process
kill -9 <PID>

Then re-run setup.

Connection succeeds but 0 tools

Cause: MCP Standard Tools SuiteApp not installed.

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

Authorization succeeds but API calls return 401

Cause: Used Administrator role for authorization.

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

Token expired?

Don't worry! The connector automatically refreshes tokens using refresh_token. If the refresh token also expires, the connector automatically opens the browser for re-authorization.

If all else fails, reset manually:

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

Available Tools (17)

After connecting, your AI assistant can call these tools:

Other AI Assistants

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "netsuite-mcp-workbuddy": {
      "command": "node",
      "args": ["/your/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

Edit .cursor/mcp.json with the same format.

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

How It Works

Two Modes, One File

Token Lifecycle

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

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:38271 callback

• Zero external dependencies — no supply chain risk

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)
│   └── ns-mcp-setup.js        # Legacy CLI version (kept for compat)
├── src/                        # Legacy TypeScript MCP server
│   ├── index.ts
│   ├── netsuite-client.ts
│   └── tools/
├── server.json                 # MCP Registry description
├── package.json
└── README.md

License

MIT