jake/lightspeed-mcp-2026-complete

Jake Shore 37c9aa1ae0 Rebrand to MCPEngage and customize Lightspeed README with retail POS power moves

2026-02-02 06:58:51 -05:00

8.1 KiB

Raw Permalink Blame History

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

🚀 Lightspeed MCP Server — 2026 Complete Version

💡 What This Unlocks

This MCP server gives AI direct access to your Lightspeed Retail POS system. Instead of manually managing sales, inventory, and customer data through the POS interface, you just tell the AI what you need — in plain English.

🎯 Retail POS Power Moves

The AI can directly control your Lightspeed Retail system with natural language:

Sales Analytics — "Show me all sales from the last 24 hours broken down by employee and location"
Inventory Tracking — "List all items with stock below reorder point and generate a purchase order list"
Product Management — "Find all items in the 'Electronics' category and show their current stock levels"
Customer Intelligence — "Get all customers who made purchases over $500 in the last month"
Register Operations — "Show me register status for all locations and today's cash counts"

🔗 The Real Power: Combining Tools

AI can chain multiple Lightspeed operations together in one conversation:

Query sales data → Filter by employee → Generate performance report
Check inventory levels → Identify low stock → Create reorder workflow
Pull customer data → Match with purchase history → Generate loyalty insights
Analyze category performance → Adjust pricing → Update inventory levels

📦 What's Inside

8 powerful API tools covering Lightspeed Retail POS operations:

list_sales — Browse completed transactions with filters
get_sale — Get complete sale details with line items and payments
list_items — Query inventory catalog with advanced filters
get_item — Get full item details including pricing and stock
update_inventory — Adjust stock levels for items at specific locations
list_customers — Browse customer database
list_categories — View product category hierarchy
get_register — Get POS terminal information and status

All with proper error handling, automatic authentication, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Local)

Clone and build:

git clone https://github.com/BusyBee3333/Lightspeed-MCP-2026-Complete.git
cd lightspeed-mcp-2026-complete
npm install
npm run build

Get your Lightspeed API credentials:
- Log in to Lightspeed Back Office
- Go to Account Settings → API Settings → Generate Token
- Complete OAuth authorization flow
- Copy your Access Token and Account ID

Configure Claude Desktop:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lightspeed": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/lightspeed-mcp-2026-complete/dist/index.js"],
      "env": {
        "LIGHTSPEED_ACCESS_TOKEN": "your-access-token-here",
        "LIGHTSPEED_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

Restart Claude Desktop

Option 2: Deploy to Railway

Click the button above
Set your Lightspeed API credentials in Railway dashboard
Use the Railway URL as your MCP server endpoint

Option 3: Docker

docker build -t lightspeed-mcp .
docker run -p 3000:3000 \
  -e LIGHTSPEED_ACCESS_TOKEN=your-token \
  -e LIGHTSPEED_ACCOUNT_ID=your-account-id \
  lightspeed-mcp

🔐 Authentication

Lightspeed uses OAuth2 authentication with Access Tokens and Account IDs.

Setup Steps:

In Lightspeed Back Office: Account Settings → API Settings
Click Generate Token or create an OAuth application
Complete the OAuth authorization flow
Save these credentials:
- Access Token — Your OAuth bearer token
- Account ID — Your Lightspeed account identifier (found in URL: /Account/{ID}/)

API Documentation: https://developers.lightspeedhq.com/retail/introduction/authentication

Token Management:

Access tokens expire after 1 hour
Use refresh tokens to obtain new access tokens
This MCP server requires a valid access token

The MCP server handles all API requests automatically using your credentials.

🎯 Example Prompts

Once connected to Claude, you can use natural language for retail POS operations:

Sales Tracking:

"Show me all completed sales from today"
"Get sales for employee ID 5 from the last week"
"List sales over $100 from location 'Downtown Store'"

Inventory Management:

"Show me all items with quantity on hand below 10"
"Update inventory for item shop ID 12345 to 50 units"
"List all items in category 'Apparel' with their stock levels"

Product Catalog:

"Get all items with UPC barcode '012345678901'"
"Show me items from manufacturer 'Apple' with inventory details"
"List all items that need reordering based on reorder point"

Customer Management:

"Find all customers with last name 'Smith'"
"Get customers who joined in the last 30 days"
"List customers with email containing '@gmail.com'"

Register Operations:

"Show me all register terminals at location 'Main St Store'"
"Get register status and cash count for register ID 3"
"List all active registers across all locations"

Analytics & Reporting:

"Generate a sales report for the last 7 days grouped by category"
"Show me top-selling items from this month"
"Export all customer purchase data from Q4 2024"

🛠️ Development

Prerequisites

Node.js 18+
npm or yarn
Lightspeed Retail account with API access
Valid OAuth access token and account ID

Setup

git clone https://github.com/BusyBee3333/Lightspeed-MCP-2026-Complete.git
cd lightspeed-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Lightspeed credentials
npm run build
npm start

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

🐛 Troubleshooting

"Authentication failed"

Verify your Access Token is current (tokens expire after 1 hour)
Check that your Account ID matches your Lightspeed account
Regenerate your access token if needed

"Tools not appearing in Claude"

Restart Claude Desktop after updating config
Check that the path in claude_desktop_config.json is absolute (not relative)
Verify the build completed successfully (dist/index.js exists)

"401 Unauthorized" errors

Your access token has likely expired (1-hour lifetime)
Use your refresh token to obtain a new access token
Update your .env or Claude config with the new token

"Rate limit exceeded"

Lightspeed has rate limits: 10 requests/second (burst), 600 requests/minute
The server respects rate limits automatically
Space out large batch operations

📖 Resources

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-tool)
Commit your changes (git commit -m 'Add amazing tool')
Push to the branch (git push origin feature/amazing-tool)
Open a Pull Request

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

Questions? Open an issue or join our Discord community.

8.1 KiB Raw Permalink Blame History