Netsuite MCP

@chatfinai/netsuite mcp

](https://badge.fury.io/js/@chatfinai%2Fnetsuite-mcp) 

一个全面的模型上下文协议（MCP）服务器，用于通过RESTlets和SuiteQL查询访问NetSuite数据。此服务器提供广泛的NetSuite集成功能，支持财务数据、客户信息、交易等。

找到我们

访问我们的官方网站：\ 👉 ChatFin——人工智能金融平台

在LinkedIn上与我们联系：\ 👉 ChatFin领英

在NetSuite上浏览我们的SuiteApp列表：\ 👉 NetSuite的ChatFin AI–SuiteApp

阅读我们最新的新闻稿：\ 👉 ChatFin发布下一代人工智能，彻底改变金融业

预订演示：\ 👉 书籍演示

特性

• 全面的NetSuite集成：访问帐户、客户、供应商、交易和财务数据
• 双服务器模式：用于web客户端的HTTP服务器和用于MCP客户端的STDIO服务器
• 高级日志记录：基于文件的日志记录，具有轮换和可配置级别
• 开发工具：用于隧道和MCP检查器支持的Ngrok集成
• 安全：CORS配置和基于环境的访问控制
• 错误处理：通过结构化日志进行稳健的错误处理
• 简易安装：作为支持TypeScript的npm包提供

系统要求

• Node.js: >= 18.0.0
• npm：>=8.0.0或 纱线: >= 1.22.0
• NetSuite：具有REST API和OAuth 2.0访问权限的活动帐户

关键依赖关系

• @模型上下文协议/sdk：MCP协议实施
• 表达：Web服务器框架
• 轴：用于NetSuite API的HTTP客户端
• 温斯顿：使用文件轮换进行日志记录
• 打字稿：TypeScript编译器和工具

先决条件

NetSuite设置要求

1. 启用SuiteQL：确保您的NetSuite帐户中启用了SuiteQL
2. 集成记录：在NetSuite中创建具有适当作用域的集成记录
3. 自定义RESTlet：为高级查询部署自定义搜索RESLet
4. 访问令牌：为您的集成生成OAuth 2.0访问令牌
5. 用户权限：确保令牌用户对以下内容具有适当的权限：

- 帐户（查看/列表） - 客户、供应商、项目（查看/列表） - 交易（查看/列表） - SuiteQL查询 - REST Web服务 - 餐厅

配置

环境设置

1. 复制示例环境文件：

   cp .env.example .env

1. 安装 setup/SuiteScript_SearchRestlet.js 在您的NetSuite SuiteScript中 RESTLet 并复制此套件脚本文件的URL。

1. 配置所需的NetSuite设置：

   # Required
   NETSUITE_REST_URL=https://your-account-id.suitetalk.api.netsuite.com/services/rest/
   NETSUITE_SEARCH_REST_LET=https://your-suite-script-url
   NETSUITE_ACCESS_TOKEN=your_jwt_access_token_here

   # Optional
   PORT=3000
   LOG_LEVEL=info
   LOG_TO_FILE=true

看 .env.example 对于所有可用的配置选项。

安装

从npm安装包：

npm install @chatfinai/netsuite-mcp

或使用纱线：

yarn add @chatfinai/netsuite-mcp

用法

选项1：用作全局包

全局安装并使用命令行工具：

# Install globally
npm install -g @chatfinai/netsuite-mcp

# Or with yarn
yarn global add @chatfinai/netsuite-mcp

# Run HTTP server
netsuite-mcp-http

# Run STDIO server
netsuite-mcp-stdio

选项2：在您的项目中使用

# Install locally
npm install @chatfinai/netsuite-mcp

# Add to your package.json scripts:
# "start:netsuite-http": "netsuite-mcp-http",
# "start:netsuite-stdio": "netsuite-mcp-stdio"

# Then run:
npm run start:netsuite-http
# or
npm run start:netsuite-stdio

选项3：与MCP客户端（Claude Desktop等）一起使用

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "netsuite": {
      "command": "netsuite-mcp-stdio",
      "env": {
        "NETSUITE_REST_URL": "https://your-account-id.suitetalk.api.netsuite.com/services/rest/",
        "NETSUITE_SEARCH_REST_LET": "https://your-account-id.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=customscript_cf_search_rl&deploy=customdeploy_cf_search_rl",
        "NETSUITE_ACCESS_TOKEN": "your_jwt_access_token_here"
      }
    }
  }
}

请参阅 examples/claude-desktop-config.json 文件以获取完整的配置示例。

选项4：程序化使用

import { McpServerFactory } from "@chatfinai/netsuite-mcp";

// Create and configure your MCP server
const server = McpServerFactory.createServer();
// ... configure as needed

查看更多示例：

• 程序化使用示例
• Claude桌面配置

开发设置

1. 克隆并安装：

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

1. 配置环境：

   cp .env.example .env
   # Edit .env with your NetSuite configuration

1. 构建并运行：

   npm run build
   npm run start:http    # HTTP server
   npm run start:stdio   # STDIO server

开发脚本

npm run dev          # HTTP server + ngrok tunnel
npm run build        # Compile TypeScript
npm run lint         # Code linting
npm run clean        # Clean build artifacts
npm run inspector    # MCP debugging tool

运行服务器

HTTP服务器模式（Web客户端）

# Start HTTP server (default port 3000)
npm run start:http

# Start with development tunneling
npm run dev

STDIO服务器模式（MCP客户端）

# Start STDIO server for MCP clients
npm run start:stdio

# Debug with MCP Inspector
npm run inspector

开发脚本

# Build and clean
npm run clean          # Clean dist and logs
npm run build          # Compile TypeScript
npm run lint           # Run ESLint

# Development
npm run dev            # Start HTTP server + ngrok tunnel
npm run ngrok          # Start ngrok tunnel only
npm run inspector      # Start MCP Inspector for debugging

# Process management
npm run stop           # Stop all server processes

服务器架构

该应用程序提供两种服务器模式：

• HTTP服务器：支持CORS的基于Express的web客户端服务器
• STDIO服务器：MCP客户端的标准I/O服务器（Claude Desktop等）

这两台服务器都使用相同的核心组件进行NetSuite集成和工具注册。

可用工具

账户管理

• get-accounts：通过过滤、排序和分页检索会计科目表
• get-account-balance：获取特定期间的账户余额
• get-accounting-periods：列出所有会计期间
• get-subsidiaries：获取附属信息

客户与供应商管理

• get-customers：检索包含联系方式的客户信息
• get-customer-details：获取详细的客户信息
• get-vendors：列出供应商及其联系方式

销售和收入

• get-invoices：检索包含客户和金额详细信息的发票
• get-invoice-items：从发票中获取行项目
• get-credit-memos：列出贷项凭单
• get-payments：获取付款记录
• get-items：检索可销售商品目录

金融交易

• get-transactions：一般交易数据
• get-bills：供应商账单和账单付款
• get-journals：日记条目

组织机构数据

• get-departments：部门列表
• get-locations：位置信息
• get-classes：班级信息
• get-posting-period：发布时段

查询功能

所有工具支持：

• 过滤：使用运算符进行基于字段的过滤
• 排序：多列排序（ASC/DESC）
• 分页：限制和偏移支持
• 计数模式：获取没有数据的记录计数
• 字段选择：选择要返回的特定字段

示例用法

{
  "name": "get-accounts",
  "arguments": {
    "Filters": [{ "Field": "Type", "Operator": "anyof", "Values": ["Income", "Expense"] }],
    "Sort": [{ "Column": "AccountNumber", "Order": "ASC" }],
    "Limit": 50,
    "Offset": 0,
    "CountOnly": false
  }
}

发展特征

Ngrok集成

该项目包括用于开发的全面ngrok配置：

# Start both server and tunnel
yarn dev

# Start tunnel only
yarn ngrok

Ngrok特点：

• 调试级别日志记录到 logs/ngrok.log （JSON格式）
• Web界面位于http://localhost:4040请求检查
• 保留域支持
• 带身份验证的自动隧道设置

MCP检查员

使用官方检查器调试您的MCP服务器：

yarn inspector

这为测试MCP工具和调试服务器行为提供了一个web界面。

记录系统

文件记录 （当 LOG_TO_FILE=true):

• 日志写入 logs/app.log
• 自动原木轮换
• 可配置的文件大小和保留期
• 结构化日志记录的JSON格式

控制台的日志 （当 LOG_TO_FILE=false):

• 彩色控制台输出
• 带颜色突出显示的JSON格式

配置：

LOG_LEVEL=info          # error, warn, info, debug
LOG_TO_FILE=true        # Enable file logging
LOG_MAX_SIZE=10m        # Max file size before rotation
LOG_MAX_FILES=5         # Number of files to retain

项目文件

• .env.example -配置模板
• examples/claude-desktop-config.json -Claude桌面设置
• examples/programmatic-usage.js -API使用示例

故障排除

身份验证问题

401身份验证错误：

• 验证 NETSUITE_ACCESS_TOKEN 已设置且有效
• 检查NetSuite集成记录是否处于活动状态
• 确保令牌未过期
• 验证REST Web服务的用户权限

403禁止错误：

• 检查特定记录类型的用户角色权限
• 确保NetSuite中启用了SuiteQL功能
• 验证对所需记录类型（帐户、客户等）的访问权限

配置问题

缺少环境变量：

• 复制 .env.example 到 .env
• 填写所有必需的NetSuite配置
• 检查控制台输出是否缺少特定变量

RESLet连接问题：

• 验证 NETSUITE_SEARCH_REST_LET URL正确
• 确保部署了自定义搜索RESTelt
• 检查RESLet脚本和部署ID

网络和连接

连接超时：

• 确认 NETSUITE_REST_URL 匹配您的帐户
• 检查防火墙设置
• 验证NetSuite帐户是否可访问

CORS问题（HTTP模式）：

• 配置 ALLOWED_ORIGINS 用于生产
• 检查浏览器开发工具是否存在CORS错误

发展问题

构建失败：

• 跑 yarn clean 然后 yarn build
• 检查控制台中的TypeScript错误
• 验证是否已安装所有依赖项

Ngrok隧道问题：

• 验证 NGROK_AUTH_TOKEN 和 NGROK_DOMAIN 已设定
• 检查ngrok帐户是否有可用隧道
• 审查 logs/ngrok.log 有关连接详细信息

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。

维护者

• ChatFinAI开源团队()

支持

如有疑问或支持，请在GitHub上发布问题或通过以下方式联系我们 .