使用说明

@chatfinai/netsuite 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设置要求

启用SuiteQL：确保您的NetSuite帐户中启用了SuiteQL
集成记录：在NetSuite中创建具有适当作用域的集成记录
自定义RESTlet：为高级查询部署自定义搜索RESLet
访问令牌：为您的集成生成OAuth 2.0访问令牌
用户权限：确保令牌用户对以下内容具有适当的权限：
- 帐户（查看/列表）
- 客户、供应商、项目（查看/列表）
- 交易（查看/列表）
- SuiteQL查询
- REST Web服务
- 餐厅

配置

环境设置

复制示例环境文件：
```
cp .env.example .env
```
安装 setup/SuiteScript_SearchRestlet.js 在您的NetSuite SuiteScript中 RESTLet 并复制此套件脚本文件的URL。

配置所需的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

查看更多示例：

开发设置

克隆并安装：

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

配置环境：

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

构建并运行：

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开源团队(support@chatfin.ai)

支持

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

使用说明

@chatfinai/netsuite mcp

找到我们

特性

系统要求

关键依赖关系

先决条件

NetSuite设置要求

配置

环境设置

安装

用法

选项1：用作全局包

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

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

选项4：程序化使用

开发设置

开发脚本

运行服务器

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

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

开发脚本

服务器架构

可用工具

账户管理

客户与供应商管理

销售和收入

金融交易

组织机构数据

查询功能

示例用法

发展特征

Ngrok集成

MCP检查员

记录系统

项目文件

故障排除

身份验证问题

配置问题

网络和连接

发展问题

许可证

维护者

支持

相关 MCP

ERP AI代理服务器

JDE E1系统配置研究工具

ERPNext扩展服务器

NetSuite智能代理连接器

Odoo销售数据服务

ERPNext集成服务器