使用说明

NetSuite MCP 服务器

一个模型上下文协议（MCP）服务器，通过OAuth 2.0结合PKCE认证提供对NetSuite数据的访问。它与任何兼容MCP的客户端无缝工作，包括Claude Code、Cursor IDE和Gemini CLI。

动机与背景

NetSuite 提供了一个官方的 AI 连接器 SuiteApp，它能够实现与 NetSuite 数据的 AI 驱动交互。然而，NetSuite 的 AI 连接器目前仅支持：

通过Anthropic的网页界面访问Claude
通过自定义GPT连接访问ChatGPT 问题：使用与MCP兼容的工具（如Claude Code、Cursor IDE、Windsurf或其他CLI/IDE环境）的开发者无法利用NetSuite的人工智能功能因为没有MCP服务器的实现。

这个MCP服务器通过以下方式解决了这一差距：

为MCP客户端（如Claude Code、Cursor、Gemini CLI等）与NetSuite的AI连接器之间搭建缺失的桥梁
实现与NetSuite的AI Connector提供的完全相同的功能，但可通过任何MCP兼容的客户端进行访问
允许开发人员在其开发环境中直接使用自然语言与NetSuite数据进行交互
保持与NetSuite官方AI Connector所要求的相同安全标准（使用PKCE的OAuth 2.0）

本质上，这款MCP服务器将NetSuite的人工智能能力引入了更广泛的MCP生态系统，使开发者能够查询业务数据、生成报告并实现自动化操作无需离开其集成开发环境（IDE）或命令行界面（CLI）即可进行NetSuite操作。

特点/功能

✅ 带有PKCE的OAuth 2.0 - 无需客户端密钥的认证安全
✅ 自动令牌刷新 - 令牌在到期前会自动刷新
✅ 环境变量支持 - 在您的MCP配置中一次性设置凭据
✅ 会话持久性 - 认证在服务器重启后仍然有效
✅ 通用MCP集成 - 与Claude Code、Cursor IDE、Gemini CLI以及其他MCP客户端兼容工作
✅（对号，表示正确、确认或完成） NetSuite MCP 工具 - 访问所有NetSuite MCP功能（包括SuiteQL、报表、保存的搜索等）
✅ 模块化架构 - 遵循单一职责原则的、整洁且易于维护的代码库

快速入门

1. NetSuite 设置

步骤1：安装NetSuite AI连接器套件应用（SuiteApp）

在创建集成记录之前，您必须安装并配置NetSuite AI Connector SuiteApp：

重要的要实现MCP（管理控制面板）功能，需要使用NetSuite AI Connector SuiteApp。如果没有它，即使经过身份验证，MCP工具也无法使用。

步骤2：创建OAuth集成记录

安装SuiteApp后，创建一个集成记录：

导航至 设置 > 集成 > 管理集成 > 新建
填写详细信息：
- 名字“MCP服务器集成”
- OAuth 2.0已检查授权码授予（或：已验证授权码授予机制）已检查公有客户端
- 重定向URI: http://localhost:8080/callback （或您的自定义端口）
保存并复制 客户端ID (消费者密钥)

注我们不需要客户端密钥（因为这是一个公共客户端，并且使用的是带PKCE的授权码模式）

2. MCP客户端配置

在您的MCP客户端配置文件中添加：

克劳德·科德： ~/.claude.json Cursor 集成开发环境 (IDE)： .cursor/mcp.json **Gemini 命令行界面 (CLI)**根据Gemini的MCP设置

选项A：使用npx（推荐 - 无需安装）

{
  "mcpServers": {
    "netsuite": {
      "command": "npx",
      "args": ["@suiteinsider/netsuite-mcp@latest"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "your-account-id",
        "NETSUITE_CLIENT_ID": "your-client-id",
        "OAUTH_CALLBACK_PORT": "8080"
      }
    }
  }
}

好处；利益：

无需手动安装
始终使用最新版本与 @latest
简洁明了的配置
MCP客户端重启后立即生效

可选环境变量：

OAUTH_CALLBACK_PORT - OAuth 回调端口（默认：8080）

选项B：本地开发环境设置

对于贡献或本地开发：

# Clone the repository
git clone https://github.com/dsvantien/netsuite-mcp-server.git
cd netsuite-mcp-server

# Install dependencies
npm install

# Test locally with npm link
npm link

然后配置为绝对路径：

{
  "mcpServers": {
    "netsuite": {
      "command": "node",
      "args": ["/absolute/path/to/netsuite-mcp-server/src/index.js"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "your-account-id",
        "NETSUITE_CLIENT_ID": "your-client-id",
        "OAUTH_CALLBACK_PORT": "8080"
      }
    }
  }
}

选项C：不使用环境变量

{
  "mcpServers": {
    "netsuite": {
      "command": "npx",
      "args": ["@suiteinsider/netsuite-mcp@latest"]
    }
  }
}

注在调用时，您需要提供凭证 netsuite_authenticate

3. 验证并使用

启动您的MCP客户端并进行身份验证：

Authenticate with NetSuite

浏览器窗口打开 → 登录NetSuite → 认证完成！

重要认证后，您需要重新启动聊天或重新连接MCP服务器以查看NetSuite工具。这是MCP的正常行为。

一旦认证成功，请使用自然语言查询：

Show me all customers
List available saved searches
Run a SuiteQL query to get sales orders from last month
Execute the "Monthly Revenue" report

建筑学

MCP Client (Claude Code, Cursor, Gemini, etc.)
       │
       │ stdio (JSON-RPC)
       ▼
┌──────────────────────────────┐
│   MCP Server (Node.js)       │
│                              │
│  ┌────────────────────────┐ │
│  │ OAuth Manager          │ │
│  │ - PKCE generation      │ │
│  │ - Local HTTP server    │ │
│  │   (port 8080 default)  │ │
│  │ - Token storage        │ │
│  └────────────────────────┘ │
│                              │
│  ┌────────────────────────┐ │
│  │ MCP Tools              │ │
│  │ - ns_runCustomSuiteQL  │ │
│  │ - ns_runReport         │ │
│  │ - ns_listSavedSearches │ │
│  └────────────────────────┘ │
└──────────────────────────────┘
       │
       │ HTTPS + Bearer Token
       ▼
┌──────────────────────────────┐
│  NetSuite MCP REST API       │
└──────────────────────────────┘

项目结构

netsuite-mcp-server/
├── src/
│   ├── index.js              # Main MCP server entry point
│   ├── oauth/
│   │   ├── manager.js        # OAuth flow orchestrator
│   │   ├── pkce.js           # PKCE challenge/verifier generation
│   │   ├── callbackServer.js # HTTP callback server with CSRF protection
│   │   ├── sessionStorage.js # Session file management
│   │   └── tokenExchange.js  # Token exchange & refresh operations
│   ├── mcp/
│   │   └── tools.js          # NetSuite MCP API client
│   └── utils/
│       └── browserLauncher.js # Cross-platform browser launcher
├── sessions/                 # OAuth tokens (gitignored)
├── authenticate.js           # Standalone CLI authentication utility
├── package.json
├── .gitignore
└── README.md

模块化设计的优势

该代码库遵循单一职责原则：

pkce.js - PKCE 工具（Base64 编码，挑战生成）
callbackServer.js 翻译为中文是：“回调服务器.js” 或者更简洁地表述为 “回调服务端脚本.js” - HTTP回调处理（防跨站请求伪造保护、HTML页面、超时处理）
sessionStorage.js（注：这通常指的是一个用于操作浏览器 sessionStorage 的JavaScript文件或模块，但直接翻译文件名时，我们通常保持原名不变，因此“sessionStorage.js”在中文中仍译为“sessionStorage.js”，不过根据语境，可以解释为“用于处理浏览器会话存储的JavaScript文件”或“会话存储JavaScript模块”。） - 会话持久性（保存、加载、清除、是否已认证）
`tokenExchange.js` 翻译成中文是：`令牌交换.js` 或 `令牌交易.js`（根据具体上下文，“tokenExchange”可能指的是令牌的交换或交易操作） NetSuite OAuth API通信（令牌交换/刷新）
browserLauncher.js 翻译为中文是：“浏览器启动器.js” 或者更简洁地表达为 “浏览器启动脚本.js”。 - 跨平台URL打开（macOS、Windows、Linux）

这种模块化结构使得：

✅ 对每个模块进行独立测试
✅ 易于维护和调试
✅ 在其他项目中的可重用性
✅ 明确的职责分离

环境变量配置

配置示例

推荐的 npx 配置：

{
  "mcpServers": {
    "netsuite": {
      "command": "npx",
      "args": ["@suiteinsider/netsuite-mcp@latest"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "123456-sb1",
        "NETSUITE_CLIENT_ID": "your-client-id-here",
        "OAUTH_CALLBACK_PORT": "8080"
      }
    }
  }
}

本地开发环境设置：

{
  "mcpServers": {
    "netsuite": {
      "command": "node",
      "args": ["path/to/src/index.js"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "123456-sb1",
        "NETSUITE_CLIENT_ID": "your-client-id-here",
        "OAUTH_CALLBACK_PORT": "8080"
      }
    }
  }
}

环境变量

NETSUITE账户ID - 您的NetSuite帐户ID（必填）
NETSUITE 客户端 ID - 您的OAuth客户端ID（必填）
OAUTH_CALLBACK_PORT 翻译为中文是：“OAuth回调端口” - OAuth回调端口（可选，默认：8080）

决议顺序（或决议排列）

首先检查参数如果 accountId 或者 clientId 作为参数提供时，请使用它们
回退到环境变量如果没有参数，则使用环境变量
验证如果两个来源都未提供凭据，则显示错误并附上说明

安全最佳实践

文件权限确保配置文件具有限制性权限
```
chmod 600 ~/.claude.json
```
**《No Secrets》（无秘密）**无需客户端密钥（使用PKCE认证）
本地令牌存储存储在（系统中的）OAuth令牌 sessions/ 目录
永不承诺不要将包含凭据的配置文件提交到Git

可用的NetSuite MCP工具

一旦认证成功，您将能够访问NetSuite自带的MCP工具：

ns_runCustomSuiteQL - 执行SuiteQL查询
ns_listAllReports - 列出可用的财务报告
ns_runReport - 执行特定报告
ns_listSavedSearches - 列出已保存的搜索
ns_runSavedSearch - 执行已保存的搜索
ns_getRecord - 检索特定记录
ns_createRecord - 创建一条新记录
ns_updateRecord - 更新现有记录
还有更多。。。

可用的确切工具取决于您的NetSuite帐户配置。

OAuth 流程

启蒙/入会用户来电 netsuite_authenticate 带有凭据
PKCE 生成服务器生成代码验证器和SHA-256挑战
授权URL服务器生成NetSuite OAuth URL并启动本地回调服务器
用户登录浏览器打开NetSuite登录页面
授权用户批准访问
回调NetSuite 重定向至 http://localhost:8080/callback 带有授权码
代币交换服务器交换代码以获取访问令牌/刷新令牌（公共客户端模式）
**会话存储（或会话级存储）**存储在中的代币 sessions/session.json （在重启后仍保持）
自动刷新令牌在即将过期时会自动刷新（设有5分钟缓冲时间）

故障排除

现在使用基于脚本位置的绝对路径

问题：“端口已被使用”

原因另一个使用OAuth回调端口的应用程序

解决方案：

# Check what's using the port (example for port 8080)
lsof -i :8080

# Option 1: Kill the process
# Option 2: Change port via environment variable

在您的MCP配置中设置自定义端口：

{
  "env": {
    "OAUTH_CALLBACK_PORT": "9000"
  }
}

记得更新您NetSuite集成中的重定向URI，以匹配新的端口！

问题：认证后工具未显示

原因MCP客户端在会话开始时缓存工具列表

解决方案：

重新开始聊天 - 开始新对话
重新连接MCP - 使用 /mcp 命令（克劳德代码）
重启应用 - 关闭并重新打开你的集成开发环境（IDE）

这是MCP（可能指某种配置或管理工具）的正常行为——工具列表在每个会话中仅获取一次。

发展

独立认证

在没有MCP客户端的情况下测试认证：

node authenticate.js <accountId> <clientId>

清算时段/清算会议

rm -rf sessions/

或者使用 netsuite_logout 在您的MCP客户端中的工具。

查看日志

所有服务器日志输出到标准错误（stderr）。当在MCP客户端中运行时，这些日志会出现在客户端的控制台/日志中。

技术细节

PKCE（Proof Key for Code Exchange）实现

代码验证器32个随机字节，采用base64url编码
代码挑战验证者的SHA-256哈希值，采用base64url编码
挑战方法S256（NetSuite 所需）

代币交换（公共客户端模式）

POST https://{accountId}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri=http://localhost:8080/callback
&client_id={client_id}
&code_verifier={verifier}

重要的不 Authorization 标题（公开客户端）。

令牌刷新

当令牌剩余有效期小于5分钟时，会自动刷新：

POST https://{accountId}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}

先决条件

Node.js 18.0.0或更高版本
NetSuite 账户 带有MCP访问权限
NetSuite AI 连接器 SuiteApp (程序包ID: 522506) 已安装并配置
NetSuite 集成记录 启用了OAuth 2.0和PKCE
MCP 客户端 - 任何兼容MCP的客户端（如Claude Code、Cursor IDE、Gemini CLI等）

许可证

麻省理工学院（MIT）

NetSuite MCP服务器

使用说明