Atlas MCP Server

An MCP (Model Context Protocol) server for integrating with the Atlas restaurant management system.

Requirements

• Node.js 18.0.0 or higher (required for native fetch and Headers APIs)

Quick start with npx

npx @atlas-kitchen/atlas-mcp

Using with Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["-y", "@atlas-kitchen/atlas-mcp"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | ATLAS_API_KEY | Yes | API key for automatic authentication | | ATLAS_GRAPHQL_ENDPOINT | No | GraphQL API base URL (default: https://api.atlas.kitchen) | | ATLAS_CLIENT_NAME | No | Client identifier for API requests (default: atlas-mcp-1.0.0) | | ATLAS_MERCHANT_ID | No | Default merchant ID on first run | | ATLAS_OUTLET_ID | No | Default outlet ID on first run (defaults to all) |

Authentication

The server authenticates automatically on startup using ATLAS_API_KEY. No manual login is needed.

• Tokens are cached to ~/.atlas-mcp/cache.json and reused across restarts
• Merchant/outlet context persists across sessions until explicitly switched
• On auth failure, the server automatically refreshes tokens or re-authenticates

Local development

npm install
cp .env.example .env  # Configure with your API key
npm run dev            # Run with tsx (development)
npm run build          # Compile TypeScript
npm start              # Run compiled JavaScript

Local development config

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/atlas-mcp/src/index.ts"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here",
        "ATLAS_MERCHANT_ID": "1"
      }
    }
  }
}

Pointing to a local backend

When iterating on Atlas APIs or developing new MCP tools, point the server to your local backend:

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/atlas-mcp/src/index.ts"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here",
        "ATLAS_GRAPHQL_ENDPOINT": "http://localhost:3000",
        "ATLAS_MERCHANT_ID": "1"
      }
    }
  }
}

The server appends /graphql automatically, so http://localhost:3000 becomes http://localhost:3000/graphql.

Tip: After changing MCP config, restart Claude Desktop (or run /exit in Claude Code) to pick up the changes.

Available tools

Authentication

• atlas_auth_status - Show current authentication and merchant context
• atlas_list_merchants - List all merchants the user can access
• atlas_list_outlets - List outlets for the current merchant
• atlas_switch_merchant - Switch merchant context (fuzzy matches by name, identifier, or ID)

Orders

• atlas_get_orders - List orders with filters (paginated, max 100 per page)
• atlas_get_order - Get detailed order information
• atlas_get_cart - Get cart details by ID
• atlas_get_pos_carts - List open POS carts (requires specific outlet)

Menu

• atlas_get_items - Search and list item catalog (paginated, max 100 per page)

Reports

• atlas_get_sales_report - Get sales analytics (max 90 day range)

Publishing to npm

Releases are published automatically via GitHub Actions when you create a GitHub release.

One-time setup

1. Go to npmjs.com token settings
2. Create a Granular Access Token with Read and write permission on packages, scoped to @atlas-kitchen
3. In the GitHub repo, go to Settings > Secrets and variables > Actions
4. Add a secret named NPM_TOKEN with the token value

Publishing a new version

npm run release         # patch: 1.1.0 → 1.1.1
npm run release:minor   # minor: 1.1.0 → 1.2.0
npm run release:major   # major: 1.1.0 → 2.0.0

This bumps the version, pushes the tag, and creates a GitHub release in one command. The GitHub Action then builds and publishes to npm automatically.

CI

Pull requests and pushes to main run a build check across Node.js 18, 20, and 22.

Usage example

# No login needed - authentication is automatic!

# Check current status
atlas_auth_status()

# Switch merchant by name (fuzzy matched)
atlas_switch_merchant({ merchant: "My Restaurant" })

# Switch merchant with specific outlet for POS
atlas_switch_merchant({ merchant: "My Restaurant", outletId: "5" })

# Query orders
atlas_get_orders({ startDate: "2026-01-01", endDate: "2026-01-31" })