MCP NetSuite Practice

Python MCP server that exposes read-only NetSuite tools for agents such as Claude Desktop or Claude Code. It lets an LLM query warehouse stock and order status without putting API keys in the client.

NetSuite access goes through a stable client interface. Local development uses a mock with sample inventory data; the same interface can later target a real sandbox via environment variables.

Product specification: project.md.
Agent quality harness: AGENTS.md (also CLAUDE.md).

Stack

• Python 3.12+

• uv

• Official mcp SDK (stdio and HTTP/SSE)

• FastAPI + Uvicorn for remote transport

• OAuth2 authorization-code + PKCE (demo IdP) and JWT bearer auth

• Pydantic / pydantic-settings for schemas and config

• Docker, Kubernetes manifests, Terraform module for cluster deploy

Related MCP server: MCP API Tool Demo

Architecture

flowchart TD
    Agent[Agent: Claude Desktop / Claude Code]
    OAuth[OAuth2 PKCE demo IdP]
    MCP[MCP Server FastAPI SSE]
    RBAC[RBAC by role]
    Tools[Tools: stock / order / admin]
    Schemas[Pydantic schemas]
    Client[NetSuite client interface]
    Mock[Mock data]
    Sandbox[NetSuite sandbox]

    Agent -->|stdio local| MCP
    Agent -->|HTTP SSE + Bearer JWT| MCP
    Agent --> OAuth
    OAuth -->|access token| Agent
    MCP --> RBAC
    RBAC --> Tools
    MCP --> Schemas
    Tools --> Client
    Client --> Mock
    Client -.-> Sandbox

The MCP server exposes typed tools to the agent. Remote mode validates a JWT from the PKCE flow and enforces least privilege (for example sales cannot call admin_reload_catalog). Tools call a NetSuite client interface so the protocol layer stays decoupled from the ERP.

How to use

Requirements: Python 3.12+, uv.

Local stdio (Claude Desktop / Claude Code)

uv sync
uv run python -m mcp_netsuite_practice

{
  "mcpServers": {
    "netsuite-practice": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/antonio/Desktop/MCP-netsuite-practice",
        "run",
        "python",
        "-m",
        "mcp_netsuite_practice"
      ]
    }
  }
}

Example prompts:

• “How much stock do we have for SKU BARRIER-01?”

• “What is the status of order SO-10042?”

Remote SSE (FastAPI)

cp .env.example .env
uv run python -m mcp_netsuite_practice --transport sse

Endpoints:

Obtain a token (PKCE), then call MCP with Authorization: Bearer <token>.

Roles: sales, ops, admin. Sales may use stock/order tools only.

Docker

docker compose up --build

Kubernetes / Terraform

• Manifests: deploy/k8s/

• Terraform module: deploy/terraform/ (see its README)

uv run pytest