netsuite-mcp

# @chatfinai/netsuite-mcp [](https://badge.fury.io/js/@chatfinai%2Fnetsuite-mcp) [](https://opensource.org/licenses/MIT) 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](https://chatfin.ai) Connect with us on LinkedIn: 👉 [ChatFin LinkedIn](https://www.linkedin.com/company/94238033/) Explore our SuiteApp listing on NetSuite: 👉 [ChatFin AI for NetSuite – SuiteApp](https://www.suiteapp.com/Chatfin-AI-for-NetSuite) Read our latest press release: 👉 [ChatFin Launches Next-Gen AI Releases to Revolutionize Finance](https://www.openpr.com/news/4205936/chatfin-launches-next-gen-ai-releases-to-revolutionize-finance) Book a Demo: 👉 [Book Demo](https://chatfin.ai/talk-to-us) ## 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](https://www.npmjs.com/package/@modelcontextprotocol/sdk)**: MCP protocol implementation - **[express](https://expressjs.com/)**: Web server framework - **[axios](https://axios-http.com/)**: HTTP client for NetSuite API - **[winston](https://github.com/winstonjs/winston)**: Logging with file rotation - **[typescript](https://www.typescriptlang.org/)**: 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: ```bash 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: ```bash # 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`](.env.example) for all available configuration options. ## Installation Install the package from npm: ```bash npm install @chatfinai/netsuite-mcp ``` Or using yarn: ```bash yarn add @chatfinai/netsuite-mcp ``` ## Usage ### Option 1: Using as a Global Package Install globally and use the command line tools: ```bash # 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 ```bash # 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): ```json { "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`](examples/claude-desktop-config.json) file for a complete configuration example. ### Option 4: Programmatic Usage ```typescript 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](./examples/programmatic-usage.js) - [Claude Desktop Configuration](./examples/claude-desktop-config.json) ### Development Setup 1. **Clone and install:** ```bash git clone https://github.com/ChatFinAI/netsuite-mcp.git cd netsuite-mcp npm install ``` 2. **Configure environment:** ```bash cp .env.example .env # Edit .env with your NetSuite configuration ``` 3. **Build and run:** ```bash npm run build npm run start:http # HTTP server npm run start:stdio # STDIO server ``` #### Development Scripts ```bash 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) ```bash # Start HTTP server (default port 3000) npm run start:http # Start with development tunneling npm run dev ``` #### STDIO Server Mode (MCP Clients) ```bash # Start STDIO server for MCP clients npm run start:stdio # Debug with MCP Inspector npm run inspector ``` ### Development Scripts ```bash # 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 ```json { "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: ```bash # 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: ```bash 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:** ```bash 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`](.env.example) - Configuration template - [`examples/claude-desktop-config.json`](examples/claude-desktop-config.json) - Claude Desktop setup - [`examples/programmatic-usage.js`](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>.