Netsuite MCP
MCP server: Netsuite MCP
Installation
npx netsuite-mcpAsk AI about Netsuite MCP
Powered by Claude Β· Grounded in docs
I know everything about Netsuite MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
@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
- Enable SuiteQL: Ensure SuiteQL is enabled in your NetSuite account
- Integration Record: Create an Integration record in NetSuite with appropriate scopes
- Custom RESTlet: Deploy the custom search RESTlet for advanced queries
- Access Token: Generate OAuth 2.0 access tokens for your integration
- 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
-
Copy the example environment file:
cp .env.example .env -
Install
setup/SuiteScript_SearchRestlet.jsin your NetSuite SuiteScripts as aRESTLetand copy the URL for this suite script file. -
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:
Development Setup
-
Clone and install:
git clone https://github.com/ChatFinAI/netsuite-mcp.git cd netsuite-mcp npm install -
Configure environment:
cp .env.example .env # Edit .env with your NetSuite configuration -
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 paginationget-account-balance: Get account balances for specific periodsget-accounting-periods: List all accounting periodsget-subsidiaries: Get subsidiary information
Customer & Vendor Management
get-customers: Retrieve customer information with contact detailsget-customer-details: Get detailed customer informationget-vendors: List vendors with contact information
Sales & Revenue
get-invoices: Retrieve invoices with customer and amount detailsget-invoice-items: Get line items from invoicesget-credit-memos: List credit memosget-payments: Get payment recordsget-items: Retrieve sellable items catalog
Financial Transactions
get-transactions: General transaction dataget-bills: Vendor bills and bill paymentsget-journals: Journal entries
Organization Data
get-departments: Department listingsget-locations: Location informationget-classes: Class informationget-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 templateexamples/claude-desktop-config.json- Claude Desktop setupexamples/programmatic-usage.js- API usage example
Troubleshooting
Authentication Issues
401 Authentication Error:
- Verify
NETSUITE_ACCESS_TOKENis 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.exampleto.env - Fill in all required NetSuite configuration
- Check console output for specific missing variables
RESTlet Connection Issues:
- Verify
NETSUITE_SEARCH_REST_LETURL is correct - Ensure custom search RESTlet is deployed
- Check RESTlet script and deployment IDs
Network & Connectivity
Connection Timeout:
- Confirm
NETSUITE_REST_URLmatches your account - Check firewall settings
- Verify NetSuite account is accessible
CORS Issues (HTTP Mode):
- Configure
ALLOWED_ORIGINSfor production - Check browser developer tools for CORS errors
Development Issues
Build Failures:
- Run
yarn cleanthenyarn build - Check TypeScript errors in console
- Verify all dependencies are installed
Ngrok Tunnel Issues:
- Verify
NGROK_AUTH_TOKENandNGROK_DOMAINare set - Check ngrok account has available tunnels
- Review
logs/ngrok.logfor 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.
