网络套件-MCP

Name: 网络套件-MCP
Author: ChatFin-Labs

作者：ChatFin-Labs2 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

@chatfinai/netsuite-mcp

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

联系我们

访问我们的官方网站：
👉 ChatFin – AI 财务平台

在LinkedIn上与我们联系：
👉 ChatFin LinkedIn

探索我们在NetSuite上的SuiteApp列表：
👉 ChatFin AI for NetSuite – SuiteApp

阅读我们的最新新闻稿：
👉 ChatFin 发布下一代AI产品以革新金融行业

预约演示：
👉 预约演示

功能

全面的NetSuite集成：访问账户、客户、供应商、交易记录和财务数据
双服务器模式：HTTP服务器用于Web客户端，STDIO服务器用于MCP客户端
高级日志记录：基于文件的日志记录，具有轮换功能和可配置级别
开发工具：Ngrok集成用于隧道连接，支持MCP Inspector
安全性：CORS配置和基于环境的访问控制
错误处理：强大的结构化日志记录错误处理
简单安装：作为npm包提供，支持TypeScript

系统要求

Node.js：>= 18.0.0
npm：>= 8.0.0 或 yarn：>= 1.22.0
NetSuite：具有REST API和OAuth 2.0访问权限的活动账户

主要依赖项

@modelcontextprotocol/sdk：MCP协议实现
express：Web服务器框架
axios：NetSuite API的HTTP客户端
winston：具有文件轮换的日志记录
typescript：TypeScript编译器和工具

前提条件

NetSuite 设置要求

启用SuiteQL：确保在您的NetSuite账户中启用了SuiteQL
集成记录：在NetSuite中创建一个具有适当范围的集成记录
自定义RESTlet：部署自定义搜索RESTlet以进行高级查询
访问令牌：为您的集成生成OAuth 2.0访问令牌
用户权限：确保令牌用户具有适当的权限：
- 账户（查看/列表）
- 客户、供应商、项目（查看/列表）
- 交易（查看/列表）
- SuiteQL查询
- REST Web服务
- RESTlet

配置

环境设置

复制示例环境文件：
```
cp .env.example .env
```
在NetSuite SuiteScripts中安装setup/SuiteScript_SearchRestlet.js作为RESTLet，并复制该套件脚本文件的URL。

配置所需的NetSuite设置：

# 必需
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

# 可选
PORT=3000
LOG_LEVEL=info
LOG_TO_FILE=true

参见.env.example了解所有可用的配置选项。

安装

从npm安装包：

npm install @chatfinai/netsuite-mcp

或使用yarn：

yarn add @chatfinai/netsuite-mcp

使用方法

选项1：作为全局包使用

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

# 全局安装
npm install -g @chatfinai/netsuite-mcp

# 或使用yarn
yarn global add @chatfinai/netsuite-mcp

# 运行HTTP服务器
netsuite-mcp-http

# 运行STDIO服务器
netsuite-mcp-stdio

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

# 本地安装
npm install @chatfinai/netsuite-mcp

# 添加到您的package.json脚本：
# "start:netsuite-http": "netsuite-mcp-http",
# "start:netsuite-stdio": "netsuite-mcp-stdio"

# 然后运行：
npm run start:netsuite-http
# 或
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";

// 创建并配置您的MCP服务器
const server = McpServerFactory.createServer();
// ... 根据需要进行配置

更多示例：

开发设置

克隆并安装：

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

配置环境：

cp .env.example .env
# 编辑.env文件以包含您的NetSuite配置

构建并运行：

npm run build
npm run start:http    # HTTP服务器
npm run start:stdio   # STDIO服务器

开发脚本

npm run dev          # HTTP服务器 + ngrok隧道
npm run build        # 编译TypeScript
npm run lint         # 代码检查
npm run clean        # 清理构建工件
npm run inspector    # MCP调试工具

运行服务器

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

# 启动HTTP服务器（默认端口3000）
npm run start:http

# 启动开发隧道
npm run dev

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

# 启动STDIO服务器供MCP客户端使用
npm run start:stdio

# 使用MCP Inspector调试
npm run inspector

开发脚本

# 构建和清理
npm run clean          # 清理dist和日志
npm run build          # 编译TypeScript
npm run lint           # 运行ESLint

# 开发
npm run dev            # 启动HTTP服务器 + ngrok隧道
npm run ngrok          # 启动ngrok隧道
npm run inspector      # 启动MCP Inspector进行调试

# 进程管理
npm run stop           # 停止所有服务器进程

服务器架构

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

HTTP服务器：基于Express的服务器，支持Web客户端和CORS
STDIO服务器：标准I/O服务器，用于MCP客户端（如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：过账期间

查询功能

所有工具均支持：

过滤：基于字段的过滤操作符
排序：多列排序（升序/降序）
分页：限制和偏移支持
计数模式：获取记录数量而不返回数据
字段选择：选择要返回的具体字段

示例用法

{
  "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配置用于开发：

# 启动服务器和隧道
yarn dev

# 启动隧道
yarn ngrok

Ngrok特性：

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

MCP Inspector

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

yarn inspector

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

日志系统

文件日志（当LOG_TO_FILE=true时）：

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

控制台日志（当LOG_TO_FILE=false时）：

带颜色的控制台输出
带颜色高亮的JSON格式

配置：

LOG_LEVEL=info          # error, warn, info, debug
LOG_TO_FILE=true        # 启用文件日志
LOG_MAX_SIZE=10m        # 文件轮换前的最大文件大小
LOG_MAX_FILES=5         # 保留的文件数量

项目文件

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

故障排除

认证问题

401 认证错误：

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

403 禁止错误：

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

配置问题

缺少环境变量：

复制.env.example到.env
填写所有必需的NetSuite配置
检查控制台输出以确定具体缺失的变量

RESTlet连接问题：

验证NETSUITE_SEARCH_REST_LET URL正确
确保自定义搜索RESTlet已部署
检查RESTlet脚本和部署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。