使用说明

netsuite mcp服务器

模型上下文协议（MCP）服务器，公开NetSuite REST API以协调Spendesk×NetSuite集成流。

建筑

该项目遵循与Spendesk MCP服务器相同的架构（mcp-poc)en生产：

Node.js 20+TypeScript
@模型上下文协议/sdk 对于MCP服务器
OAuth 1.0a TBA（HMAC-SHA256） 为NetSuite进行身份验证
两种启动模式 :
- stdio ：对于Cursor，Claude桌面
- HTTP Streamable ：用于灰尘、ChatGPT、云部署

先决条件

1.Node.js 20+

node --version  # v20+

2.证书NetSuite（沙盒）

你必须创建一个整合 et un 访问令牌 在您的NetSuite沙盒帐户中：

创建集成

进去 设置>集成>管理集成>新建
填写：
- 姓名： Spendesk MCP Server
- 国家： Enabled
- 汽车 基于令牌的身份验证
保存并记录 消费者密钥 和 消费者秘密

创建访问令牌

进去 设置>用户/角色>访问令牌>新建
选择：
- 应用程序名称： Spendesk MCP Server
- 用户：您的用户（具有正确的角色）
- 角色： 管理员 或具有REST API访问权限的自定义角色
保存并记录 令牌ID 和 令牌密钥

安装

# Clone le repo
cd netsuite-mcp-server

# Installe les dépendances
npm install

# Configure les credentials
cp .env.example .env
# puis édite .env avec tes vraies credentials

文件 `.env`

# NetSuite Sandbox credentials
NETSUITE_ACCOUNT_ID=TSTDRV1234567        # ton account ID sandbox
NETSUITE_CONSUMER_KEY=xxx
NETSUITE_CONSUMER_SECRET=xxx
NETSUITE_TOKEN_ID=xxx
NETSUITE_TOKEN_SECRET=xxx

# HTTP server (pour mode HTTP Streamable)
PORT=3001
HOST=0.0.0.0
ALLOWED_HOSTS=localhost

⚠️ 安全 : .env 在 .gitignore永远不要提交你真正的证书。

使用

模式stdio（光标、克劳德桌面）

# Build
npm run build

# Lancer le serveur stdio
npm start

配置光标

添加到MCP配置（~/.cursor/mcp.json 或等效物）：

{
  "mcpServers": {
    "netsuite": {
      "command": "node",
      "args": ["/chemin/absolu/vers/netsuite-mcp-server/dist/index.js"],
      "env": {
        "NETSUITE_ACCOUNT_ID": "TSTDRV1234567",
        "NETSUITE_CONSUMER_KEY": "xxx",
        "NETSUITE_CONSUMER_SECRET": "xxx",
        "NETSUITE_TOKEN_ID": "xxx",
        "NETSUITE_TOKEN_SECRET": "xxx"
      }
    }
  }
}

HTTP可流模式（灰尘、ChatGPT、部署）

# Build
npm run build

# Lancer le serveur HTTP
npm run start:http

服务器正在监听 http://0.0.0.0:3001 默认情况下。

终点：

GET / ：健康检查
POST /mcp ：端点MCP流式HTTP（JSON-RPC+SSE）

HTTP服务器测试

# Dans un terminal, lance le serveur :
npm run start:http

# Dans un autre terminal, teste :
npm run test:http

可用的 MCP 工具

服务器公开 25工具 要协调Spendesk×NetSuite流：

供应商（供应商）

netsuite_get_vendors ：按分页列出供应商
netsuite_get_vendor ：按ID获取供应商

供应商发票（Vendor Bills）

netsuite_get_vendor_bills ：列出供应商账单
netsuite_get_vendor_bill ：按ID获取供应商账单
netsuite_create_vendor_bill ：使用费用线创建新的供应商账单（支持 department, location, class)
netsuite_update_vendor_bill ：更新现有供应商账单

日记账条目（会计记录）

netsuite_get_journal_entries ：列出日记条目
netsuite_create_journal_entry ：使用借记/贷记行创建条目日志（支持 department, location, class)

员工（主数据）

netsuite_get_employees ：李斯特员工（倒匹配Spendesk会员→ NetSuite员工）
netsuite_get_employee ：按ID获取员工

费用报告（Notes de Frais）

netsuite_get_expense_reports ：列出费用报告
netsuite_create_expense_report ：为具有支出项目的员工创建支出报告（支持外币、分析）

账单付款（供应商付款）

netsuite_create_bill_payment ：创建供应商付款并将其应用于一个或多个供应商账单

供应商信用（供应商资产）

netsuite_get_vendor_credits ：列出供应商信用
netsuite_create_vendor_credit ：创建供应商信用票据，并可选地将其应用于供应商票据

参考

netsuite_get_accounts ：列出会计科目表
netsuite_get_departments ：部门/成本中心列表
netsuite_get_subsidiaries ：子公司列表
netsuite_get_tax_codes ：税号列表
netsuite_get_currencies ：货币列表

分析领域（Analytics）

netsuite_get_locations ：租金列表（分析维度）
netsuite_get_classifications ：分类/类列表（分析维度）

NetSuite的三个分析维度（department, location, class）所有创作工具（供应商账单、日记账条目、费用报告、供应商信用）都支持。

文件柜（附件）

netsuite_upload_file ：将文件（pdf、png、jpeg…）上传到文件柜NetSuite，返回文件ID
netsuite_attach_file_to_record ：将文件（通过其ID）附加到NetSuite记录（供应商账单、费用报告、供应商信用）

SuiteQL

netsuite_execute_suiteql ：执行SuiteQL查询（只读，仅选择）

SuiteQL查询示例：

-- Trouver un vendor par externalId
SELECT id, companyName, email FROM vendor WHERE externalId = 'spk_supplier_xxx'

-- Lister les vendor bills non approuvées
SELECT id, tranId, entity, amount, status FROM transaction
WHERE type = 'VendBill' AND status = 'VendBill:B'

-- Mapping account par numéro
SELECT id, acctNumber, acctName, type FROM account WHERE acctNumber LIKE '6%'

测试

# Test de connexion NetSuite (liste 5 vendors)
npm run test:vendors

# Test du serveur HTTP MCP complet
npm run test:http

# Test de tous les 25 tools MCP
npm run test:all

详细文件

有关完整的指南和业务报告，请参阅文件夹 docs/ :

部署指南： docs/deploy/ （快速入门、检查表、完整铁路/粉尘指南）
权限和设置NetSuite： docs/setup/
测试场景和报告： docs/testing/
SuiteQL和后备REST： docs/suiteql/
映射层级（供应商、账单、付款、费用报告）： docs/overview/, docs/vendors/, docs/bill-payments/

部署

码头工人

一个 Dockerfile 计划（如有必要，可创建，灵感来自 mcp-poc) :

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist ./dist
EXPOSE 3001
CMD ["node", "dist/server-http.js"]

铁路/渲染/Fly.io

配置les 环境变量 （5个证书NetSuite+PORT）
构建命令： npm run build
启动命令： npm run start:http
端口： 3001

建筑技术

src/
├── index.ts                    # Entry point stdio
├── server-http.ts              # Entry point HTTP Streamable (Hono)
├── netsuite-client.ts          # Client REST NetSuite (OAuth 1.0a)
├── tools/
│   ├── index.ts                # Enregistre tous les tools
│   ├── vendors.ts              # Tools vendors
│   ├── vendor-bills.ts         # Tools vendor bills (+ location, class)
│   ├── journal-entries.ts      # Tools journal entries (+ location, class)
│   ├── employees.ts            # Tools employees (NEW)
│   ├── expense-reports.ts      # Tools expense reports (NEW)
│   ├── payments.ts             # Tools bill payments (NEW)
│   ├── vendor-credits.ts       # Tools vendor credits (NEW)
│   ├── analytics.ts            # Tools locations + classifications (NEW)
│   ├── file-cabinet.ts         # Tools file upload + attach (NEW)
│   ├── reference.ts            # Tools référentiel
│   └── suiteql.ts              # Tool SuiteQL
└── utils/
    ├── oauth1.ts               # Génération header OAuth 1.0a HMAC-SHA256
    └── pagination.ts           # Helper pagination NetSuite

身份验证NetSuite

客户利用率 具有HMAC-SHA256签名的OAuth 1.0a，从零开始实现（没有外部库） utils/oauth1.ts.

每个请求都包括一个标题 Authorization: OAuth ... 具有：

oauth_consumer_key, oauth_token
oauth_signature_method=HMAC-SHA256
oauth_timestamp, oauth_nonce
oauth_signature （HMAC-SHA256签名基础字符串）

错误管理

所有MCP工具捕获NetSuite错误并返回清晰消息，例如：

NetSuite 401: Invalid credentials. Check NETSUITE_TOKEN_ID and NETSUITE_TOKEN_SECRET.
NetSuite 400: Bad Request

幂等性

创建工具接受一个参数 externalId （例如： spendesk_supplier_id, spendesk_payable_id）以避免在代理重放流时重复。

日志

日志在 标准错误 （不是stdout，它是为stdio MCP协议保留的）。

示例：

Starting NetSuite MCP HTTP server on 0.0.0.0:3001
Health check: http://0.0.0.0:3001/
MCP endpoint: http://0.0.0.0:3001/mcp

资源

故障排除

401无效凭证

检查：

正确填写了5个环境变量
访问令牌未过期（在NetSuite中：设置>访问令牌）
与令牌关联的角色具有REST API权限

端点上的错误400错误请求

一些参考端点（/account, /department等）可能不存在或需要不同的语法，具体取决于NetSuite版本。使用 SuiteQL 作为替代方案：

SELECT id, acctNumber, acctName FROM account LIMIT 10

HTTP服务器没有响应

检查端口3001是否空闲：

lsof -ti:3001  # Si un PID apparaît, kill-le
npm run start:http

许可证

麻省理工学院