OpenSuiteMCP
Source-available NetSuite MCP client — chat UI for NetSuite’s AI Connector Service, MCP Standard Tools, Companion prompt library, and SuiteCloud Agent Skills.
Bring your own LLM keys (Google Gemini, Anthropic Claude, OpenAI, or an OpenAI-compatible endpoint). Self-host for internal use. Commercial rights reserved by Unstacked Apps, LLC.
Current release: v5.13.0 · Changelog
Main chat UI.
What’s in 5.13
- Oracle’s SuiteSkills — the five business skills Oracle announced on 2026-10-26, holding 48 runbooks, sync with the rest of Oracle’s skills. Switch one on under Skills → Oracle
- Oracle skills sync whole — every reference file, and no 32,000-character cut on
SKILL.md
What’s in 5.12
- Deploy to AWS from this repo —
pnpm bootstrap:aws creates the EC2 server, installs OpenSuiteMCP over SSH and prints the address; pnpm teardown:aws deletes what it created. See docs/deploy-aws.md
What’s in 5.11
- Install on a server with one command — on your own Linux server or on AWS, over SSH. See Install on a server
- Update from the app — Admin → App updates on an org install, Settings → General on a solo install: update now, or turn on automatic updates.
osmcp update does the same over SSH, and rolls back a release that doesn't start
- Turn on the instance report from the admin — Admin → Instance report generates the token, with no restart
Earlier releases are in the changelog.
Personas
Open Personas from the App Portal or the header badge on a new chat. Pick a built-in specialist or Create my own… to run the interview builder (guided chat that drafts a custom persona playbook).
Built-in personas ship in .personas/*.md in this repo. Custom personas are stored per user in Postgres.
Pair skills to a persona on the Skills tab of its editor — built-in personas included, where the tab is the only part you can change. A paired skill applies whenever that persona is the one working, even when its mode is Slash command.
Clone copies a persona, including the skills it carries.
Skills
Open Skills from the App Portal (or the sidebar). Four sources, three invocation modes:
| Source | Default | How it works |
|---|
| Oracle | Disabled | Shared pack; Auto / Slash command / Disabled. Core AI Connector instructions stay Auto. |
| Community | Disabled | Shared pack from opensuitemcp-community-skills; Auto / Slash command / Disabled |
| Connected | Slash command | Paste a public GitHub repo/folder URL; Auto / Slash command / Disabled |
| Custom | Auto | Paste/import custom SKILL.md; Auto / Slash command / Disabled |
Auto is injected into every new message. Slash command is injected when you type /skill-name. Composer / lists Auto and Slash command skills. A mode change applies to every message you send after it, in every thread.
A skill written by a connected agent is credited to the agent and starts as Slash command, so it applies when you invoke it or when a persona carrying it is working. A skill you add yourself starts as Auto.
Clone on a custom skill row copies it into one you own, including a skill your organization published. Over MCP, osmcp_clone_skill copies any of the four sources. Import .md or .zip in the skill editor loads a SKILL.md and the files beside it; the download button on a custom row returns the folder as a .zip.
A skill can carry reference files beside its SKILL.md, the way Oracle and Community packs do. SKILL.md holds up to 32,000 characters. Beside it, up to 32 reference files, 64,000 characters each and 256,000 across them.
Shared packs are not vendored in git. Sync them with:
pnpm skills:sync
That downloads every netsuite- skill folder in Oracle’s SuiteCloud SDK repo — Agent Skills and SuiteSkills — into .data/oracle-skills (or ORACLE_SKILLS_DIR), and Community skills into .data/community-skills (or COMMUNITY_SKILLS_DIR). The container runs it on every start. New upstream skills appear as Off until you set a mode; removed upstream skills are pruned. Optional: GITHUB_TOKEN for higher GitHub API limits.
Connected examples:
https://github.com/mattpocock/skills/tree/main/skills/productivityowner/repo shorthand
Public repos only. Synced files live under .data/connected-skills/<userId>/<sourceId>/ (or CONNECTED_SKILLS_DIR).
Skills panel — Oracle, Community, Connected, and Custom.
Prompts
Open Prompts for the Companion SuiteApp library (requires NetSuite connected with Companion available). Filter by category, industry, or role; open a template; fill required placeholders; then use it in chat.
Companion prompt library — browse and fill-in.
Docs: Companion SuiteApp
NetSuite MCP tools
With AI Connector + MCP Standard Tools connected, chat can run SuiteQL, records, reports, saved searches, and related MCP tools against your account.
NetSuite MCP tools in a conversation.
MCP server (act on behalf of a user)
OpenSuiteMCP can also be an MCP server, so an external AI agent works
inside a user's NetSuite workspace as that user — their connected account,
their permissions, their tool policy.
Create the app under App Portal → Agent apps → New app, choosing how it
connects:
- OAuth 2.1 — every install is its own OAuth 2.1 authorization server. A client
that supports DCR registers itself from the URL alone; for one that does not,
tick Connector needs a client ID and secret and paste its callback URL.
It sends you here to approve the app, then refreshes its own token.
- Bearer auth — a token in a header, for an app with no person behind it, a
client with no OAuth support, or an install that is not on HTTPS.
Either way the app reaches what you have enabled in OpenSuiteMCP, and both appear
in one list you can rename, re-role and revoke. The server URL derives from your
install's public address, so self-hosted, sandbox and hosted installs each have
their own.
A connected agent reads and writes the workspace's skills: osmcp_create_skill,
osmcp_clone_skill, osmcp_update_skill, osmcp_delete_skill,
osmcp_read_skill_file and osmcp_pair_skills, alongside the persona and chat
tools. An agent may revise or delete only agent-authored skills; anything else it
clones first.
The server answers prompts/list and prompts/get as well as tools/*. Four
built-ins ship — Start a NetSuite task, Choose the right specialist,
Record this session in OpenSuiteMCP, Save what you learned as a skill —
alongside every prompt your NetSuite Companion library publishes, named
netsuite_…. Claude Desktop does not list them today.
The exact thing to paste, per client, is in
Connect an agent. Protocol and tool reference:
MCP server.
Install on a server
curl -fsSL https://raw.githubusercontent.com/unstackedapps/opensuitemcp/main/deploy/install.sh \
| sudo bash -s -- --domain osmcp.example.com --mode org --root-email [email protected]
The rest of this README runs OpenSuiteMCP from source, for development.
Prerequisites
- Node.js 22+ and pnpm
- Docker (Docker Desktop on macOS/Windows, or Docker Engine on Linux) for local PostgreSQL, Redis, and SearXNG via
pnpm setup:backend
- An active NetSuite user who can sign in — the person who completes first-run setup must have a working NetSuite login today:
- Organization:
OSMCP_ROOT_EMAIL must be that user’s NetSuite email; they sign in on /setup via NetSuite OIDC (recommended) or local password with the same email
- Solo: use NetSuite sign-in on
/login with an account you can access now (local email/password is optional, but you still need NetSuite for MCP connect)
- A NetSuite account with:
- An LLM API key — Google Gemini, Anthropic Claude, OpenAI, or any OpenAI-compatible HTTPS endpoint (custom base URL + key)
Quick Start
-
Install dependencies
pnpm install
-
Run automated setup
pnpm bootstrap:local
Or run the steps manually (pnpm setup:backend, then pnpm skills:sync, pnpm db:migrate, pnpm dev).
setup:backend generates secrets, asks organization vs solo install mode, and writes:
.env.local — app / migrate vars (POSTGRES_URL, REDIS_URL, AUTH_SECRET, OSMCP_INSTALL_MODE, etc.)docker/.env — Compose vars (PROJECT_NAME, POSTGRES_PW, REDIS_PW); gitignored
| Install mode | Set in .env.local | First-run experience |
|---|
| Organization (default prompt) | OSMCP_INSTALL_MODE=org and OSMCP_ROOT_EMAIL (active NetSuite user email) | /setup until org owner exists |
| Solo (consultant / individual) | OSMCP_INSTALL_MODE=solo | /login — NetSuite sign-in or local email/password |
For org installs, NetSuite OIDC login is optional during setup (account ID + client ID). You can enter them on /setup instead. See NetSuite OIDC login. MCP account connect in the App Portal is separate (different OAuth integration and callback).
The script can start Docker services (PostgreSQL, Redis, SearXNG). If Docker was not running during setup, start Docker Desktop/Engine, then:
docker compose --env-file docker/.env -f docker/docker-compose.yml -p opensuitemcp up -d
Use your project name instead of opensuitemcp if you chose a custom name during setup.
Fresh reset (local dev): pnpm reset:backend — tears down Docker volumes, removes env files, waits briefly, then runs full bootstrap and starts dev. To only tear down without reinstalling: pnpm teardown:backend.
Install environment variables
Written by pnpm setup:backend (or set manually for production):
| Variable | Org | Solo | Purpose |
|---|
OSMCP_INSTALL_MODE | org | solo | Locks first-run to /setup or /login |
OSMCP_ROOT_EMAIL | Required | — | Active NetSuite user email; only this user can become org owner on /setup |
OSMCP_NS_ACCOUNT_ID | Optional | Optional | NetSuite account for OIDC app login |
OSMCP_NS_OIDC_CLIENT_ID | Optional | Optional | OIDC integration client ID for app login |
OSMCP_ENABLE_GUEST | — | — | Set true for guest auto-login in demo/e2e |
OSMCP_INSTANCE_REPORT_TOKEN | Optional | Optional | Bearer token of 32+ characters that turns on /api/instance/report; see Instance report |
Upgrading an existing install with users already in the database: see docs/org-admin-upgrade.md.
NetSuite setup (short)
- In NetSuite, ensure AI Connector and the MCP Standard Tools SuiteApp are available for your account.
- In OpenSuiteMCP → NetSuite, add your account ID (e.g.
1234567 or 1234567-sb1).
- Follow the in-app Integration instructions (admin once per account), then Connect (MCP OAuth — scope mcp, callback
/api/netsuite/callback).
- Confirm the header status chip shows connected before running SuiteQL / record tools.
App login vs MCP connect: NetSuite OIDC login is a separate integration (OIDC Provider, callback /api/auth/netsuite/callback). MCP connect in the portal uses the MCP integration only (callback /api/netsuite/callback).
Official references:
Usage limits (optional)
Override with env vars:
| Variable | Default (OSS) | Purpose |
|---|
MAX_MESSAGES_PER_DAY_REGULAR | 100 | Signed-in user messages / 24h |
MAX_MESSAGES_PER_DAY_GUEST | 20 | Guest messages / 24h (only if OSMCP_ENABLE_GUEST=true) |
CHAT_BURST_LIMIT_PER_MINUTE | unset / 0 (off) | Redis burst cap; fail-open if Redis is down |
MCP_CALL_LIMIT_PER_MINUTE | unset / 0 (off) | Per-API-key MCP tool calls / minute; fail-open if Redis is down |
Contributors
Third-party libraries and templates are listed in ATTRIBUTION.md.
License & notices
Free: your organization may self-host for its own internal use. Paid: commercial delivery, paid implementation, or paid support of this product — only via Unstacked Apps ([email protected]). Third parties may not charge to implement or commercially support this codebase.
Hosted product (separate from this repo): opensuitemcp.com
