@chatfinai/netsuite-mcp

A comprehensive Model Context Protocol (MCP) server for accessing NetSuite data through RESTlets and SuiteQL queries. This server provides extensive NetSuite integration capabilities with support for financial data, customer information, transactions, and more.

Find Us

Visit our official website:
👉 ChatFin – AI Finance Platform

Connect with us on LinkedIn:
👉 ChatFin LinkedIn

Explore our SuiteApp listing on NetSuite:
👉 ChatFin AI for NetSuite – SuiteApp

Read our latest press release:
👉 ChatFin Launches Next-Gen AI Releases to Revolutionize Finance

Book a Demo:
👉 Book Demo

Features

• Comprehensive NetSuite Integration: Access accounts, customers, vendors, transactions, and financial data
• Dual Server Modes: HTTP server for web clients and STDIO server for MCP clients
• Advanced Logging: File-based logging with rotation and configurable levels
• Development Tools: Ngrok integration for tunneling and MCP Inspector support
• Security: CORS configuration and environment-based access controls
• Error Handling: Robust error handling with structured logging
• Easy Installation: Available as an npm package with TypeScript support

System Requirements

• Node.js: >= 18.0.0
• npm: >= 8.0.0 or yarn: >= 1.22.0
• NetSuite: Active account with REST API and OAuth 2.0 access

Key Dependencies

• @modelcontextprotocol/sdk: MCP protocol implementation
• express: Web server framework
• axios: HTTP client for NetSuite API
• winston: Logging with file rotation
• typescript: TypeScript compiler and tooling

Prerequisites

NetSuite Setup Requirements

1. Enable SuiteQL: Ensure SuiteQL is enabled in your NetSuite account
2. Integration Record: Create an Integration record in NetSuite with appropriate scopes
3. Custom RESTlet: Deploy the custom search RESTlet for advanced queries
4. Access Token: Generate OAuth 2.0 access tokens for your integration
5. User Permissions: Ensure the token user has appropriate permissions for:
   • Accounts (View/List)
   • Customers, Vendors, Items (View/List)
   • Transactions (View/List)
   • SuiteQL queries
   • REST Web Services
   • RESTlets

Configuration

Environment Setup

1. Copy the example environment file:

   cp .env.example .env
   

2. Install setup/SuiteScript_SearchRestlet.js in your NetSuite SuiteScripts as a RESTLet and copy the URL for this suite script file.

3. Configure required NetSuite settings:

   # 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
   

See .env.example for all available configuration options.

Installation

Install the package from npm:

npm install @chatfinai/netsuite-mcp

Or using yarn:

yarn add @chatfinai/netsuite-mcp

Usage

Option 1: Using as a Global Package

Install globally and use the command line tools:

# 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

Option 2: Using in Your Project

# 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

Option 3: Using with MCP Clients (Claude Desktop, etc.)

Add to your MCP client configuration (e.g., 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"
      }
    }
  }
}

See the examples/claude-desktop-config.json file for a complete configuration example.

Option 4: Programmatic Usage

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

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

See more examples:

• Programmatic Usage Example
• Claude Desktop Configuration

Development Setup

1. Clone and install:

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

2. Configure environment:

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

3. Build and run:

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

Development Scripts

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

Running the Server

HTTP Server Mode (Web Clients)

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

# Start with development tunneling
npm run dev

STDIO Server Mode (MCP Clients)

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

# Debug with MCP Inspector
npm run inspector

Development Scripts

# 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

Server Architecture

The application provides two server modes:

• HTTP Server: Express-based server for web clients with CORS support
• STDIO Server: Standard I/O server for MCP clients (Claude Desktop, etc.)

Both servers use the same core components for NetSuite integration and tool registration.

Available Tools

Account Management

• get-accounts: Retrieve chart of accounts with filtering, sorting, and pagination
• get-account-balance: Get account balances for specific periods
• get-accounting-periods: List all accounting periods
• get-subsidiaries: Get subsidiary information

Customer & Vendor Management

• get-customers: Retrieve customer information with contact details
• get-customer-details: Get detailed customer information
• get-vendors: List vendors with contact information

Sales & Revenue

• get-invoices: Retrieve invoices with customer and amount details
• get-invoice-items: Get line items from invoices
• get-credit-memos: List credit memos
• get-payments: Get payment records
• get-items: Retrieve sellable items catalog

Financial Transactions

• get-transactions: General transaction data
• get-bills: Vendor bills and bill payments
• get-journals: Journal entries

Organization Data

• get-departments: Department listings
• get-locations: Location information
• get-classes: Class information
• get-posting-period: Posting periods

Query Features

All tools support:

• Filtering: Field-based filtering with operators
• Sorting: Multi-column sorting (ASC/DESC)
• Pagination: Limit and offset support
• Count Mode: Get record counts without data
• Field Selection: Choose specific fields to return

Example Usage

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

Development Features

Ngrok Integration

The project includes comprehensive ngrok configuration for development:

# Start both server and tunnel
yarn dev

# Start tunnel only
yarn ngrok

Ngrok Features:

• Debug-level logging to logs/ngrok.log (JSON format)
• Web interface at http://localhost:4040 for request inspection
• Reserved domain support
• Automatic tunnel setup with authentication

MCP Inspector

Debug your MCP server with the official inspector:

yarn inspector

This provides a web interface for testing MCP tools and debugging server behavior.

Logging System

File Logging (when LOG_TO_FILE=true):

• Logs written to logs/app.log
• Automatic log rotation
• Configurable file size and retention
• JSON format for structured logging

Console Logging (when LOG_TO_FILE=false):

• Colorized console output
• JSON format with color highlighting

Configuration:

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

Project Files

• .env.example - Configuration template
• examples/claude-desktop-config.json - Claude Desktop setup
• examples/programmatic-usage.js - API usage example

Troubleshooting

Authentication Issues

401 Authentication Error:

• Verify NETSUITE_ACCESS_TOKEN is set and valid
• Check NetSuite integration record is active
• Ensure tokens are not expired
• Verify user permissions for REST Web Services

403 Forbidden Error:

• Check user role permissions for specific record types
• Ensure SuiteQL feature is enabled in NetSuite
• Verify access to required record types (Accounts, Customers, etc.)

Configuration Issues

Missing Environment Variables:

• Copy .env.example to .env
• Fill in all required NetSuite configuration
• Check console output for specific missing variables

RESTlet Connection Issues:

• Verify NETSUITE_SEARCH_REST_LET URL is correct
• Ensure custom search RESTlet is deployed
• Check RESTlet script and deployment IDs

Network & Connectivity

Connection Timeout:

• Confirm NETSUITE_REST_URL matches your account
• Check firewall settings
• Verify NetSuite account is accessible

CORS Issues (HTTP Mode):

• Configure ALLOWED_ORIGINS for production
• Check browser developer tools for CORS errors

Development Issues

Build Failures:

• Run yarn clean then yarn build
• Check TypeScript errors in console
• Verify all dependencies are installed

Ngrok Tunnel Issues:

• Verify NGROK_AUTH_TOKEN and NGROK_DOMAIN are set
• Check ngrok account has available tunnels
• Review logs/ngrok.log for connection details

License

This project is licensed under the MIT License. See the LICENSE file for details.

Maintainers

• ChatFinAI Open Source Team (support@chatfin.ai)

Support

For questions or support, open an issue on GitHub or contact us at support@chatfin.ai.