npm package: @joinluminous/mcp-server
Description: MCP server for the Luminous API — products, orders, inventory, companies, and more
Latest version: 1.0.0

# @joinluminous/mcp-server

MCP server for the [Luminous](https://joinluminous.com) API. Gives Claude access to your products, orders, inventory, companies, contacts, and more.

## Setup

### Claude Desktop

Add this to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "luminous": {
      "command": "npx",
      "args": ["-y", "@joinluminous/mcp-server"],
      "env": {
        "LUMINOUS_SUBDOMAIN": "your-company",
        "LUMINOUS_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

Replace `your-company` with your Luminous subdomain (the part before `.api.joinluminous.com`) and `your-api-token` with your API key.

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "luminous": {
      "command": "npx",
      "args": ["-y", "@joinluminous/mcp-server"],
      "env": {
        "LUMINOUS_SUBDOMAIN": "your-company",
        "LUMINOUS_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Getting Your API Token

Contact [developers@joinluminous.com](mailto:developers@joinluminous.com) to request an API token, or generate one from your Luminous admin settings.

## Available Tools

### Core CRUD

| Tool | Description |
|------|-------------|
| `luminous_list` | List any resource with filters, pagination, and sorting |
| `luminous_get` | Get a single resource by ID |
| `luminous_create` | Create a new resource |
| `luminous_update` | Update a resource by ID |
| `luminous_delete` | Delete a resource by ID |

### Inventory

| Tool | Description |
|------|-------------|
| `luminous_inventory_stocks` | Get current stock levels |
| `luminous_inventory_adjust` | Adjust stock quantities |

### Sales Orders

| Tool | Description |
|------|-------------|
| `luminous_sales_order_shipments` | List or create shipments |
| `luminous_sales_order_export` | Incremental export of changed orders |

### Purchase Orders

| Tool | Description |
|------|-------------|
| `luminous_purchase_order_payments` | Create, update, or delete payments |

### Products

| Tool | Description |
|------|-------------|
| `luminous_product_upsert` | Create or update a product by SKU |
| `luminous_product_pricing` | Get pricing, optionally per-company |

### Companies

| Tool | Description |
|------|-------------|
| `luminous_company_sub_resources` | List contacts, products, or price overrides for a company |

### Tags & Custom Fields

| Tool | Description |
|------|-------------|
| `luminous_tags` | Get, attach, detach, or replace tags |
| `luminous_custom_fields` | Get or update custom field values |

## Supported Resources

products, sales-orders, purchase-orders, inventory, companies, contacts, invoices, boms, warehouses, locations, transfer-orders, receiving-reports, price-schedules, price-levels

## Filtering

Filters use Luminous query syntax:

```
{"sku[contains]": "BOLT", "type": "PRODUCT", "created_at[gte]": "2025-01-01"}
```

**Operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `notcontains`, `in`, `notin`, `set`, `notset`

## API Documentation

Full API docs: [docs.joinluminous.com](https://docs.joinluminous.com)

## License

MIT