Storage Essentials MCP Server (Read-Only)

Model Context Protocol (MCP) server for querying Storage Essentials API V2. This is a read-only server that provides access to retrieve data without creating or modifying records.

Features

• Read-Only Operations: Safe querying of companies, facilities, units, and promotions
• V2 API Support: Full access to V2 REST API endpoints
• Auto-authentication: Automatic token management and refresh
• Environment Support: Local, Staging, and Production environments
• Type-safe: Full TypeScript implementation with type definitions
• Client-side Pagination: Built-in pagination support for large datasets

Installation

npm install
npm run build

Configuration

Environment Variables

The following environment variables are required:

# Required
SE_API_KEY=your_api_key_here

# Optional (defaults to staging)
SE_ENVIRONMENT=staging  # Options: local, staging, production
SE_BASE_URL=https://api-storageessentials.golocaldev.com  # Override default URL

Claude Desktop Configuration

Add to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "storage-essentials": {
      "command": "npx",
      "args": ["@golocalinteractive/storage-essentials-mcp"],
      "env": {
        "SE_API_KEY": "your_api_key_here",
        "SE_ENVIRONMENT": "staging"
      }
    }
  }
}

Available Tools

Naming Convention: Tools follow a plural/singular pattern - plural names (e.g., GetCompanies) return collections, singular names (e.g., GetCompany) require an ID parameter.

Companies

• seV2GetCompanies - Get all companies
• seV2GetCompany - Get a specific company (requires company_id)
• seV2GetCompanyCredentials - Get all credentials for a company (requires company_id)
• seV2GetCompanyRentals - Get all rentals for a company (requires company_id)

Facilities

• seV2GetFacilities - Get all facilities (with optional company filter)
• seV2GetFacility - Get a specific facility (requires facility_id)

Units

• seV2GetUnits - Get all units for a facility (filterable by status, type) with pagination support (requires facility_id)
• seV2GetUnit - Get a specific unit (requires facility_id and unit_id)

Unit Types & Categories

• seV2GetUnitTypes - Get all unit types for a facility (e.g., 5x5, 10x10) with pagination support (requires facility_id)
• seV2GetUnitCategories - Get all unit categories for a facility (e.g., Climate Controlled) (requires facility_id)

Promotions

• seV2GetPromotions - Get all promotions for a facility (requires facility_id)
• seV2GetPromotion - Get a specific promotion (requires facility_id and promotion_id)

Usage Examples

Example 1: Get All Facilities

// Using seV2GetFacilities tool
{
  "search": "Kansas City"  // Optional search filter
}

Example 2: Get Available Units with Pagination

// Using seV2GetUnits tool
{
  "facility_id": "12345",
  "status": "Available",
  "page": 1,
  "per_page": 20
}

Example 3: Get Company Details

// Using seV2GetCompany tool
{
  "company_id": "67890"
}

Example 4: List Promotions for a Facility

// Using seV2GetPromotions tool
{
  "facility_id": "12345"
}

Development

Running in Development Mode

npm run dev

Building

npm run build

Watch Mode

npm run watch

Local Testing with Claude Code

Step 1: Build the Project

npm install
npm run build

Step 2: Get Your API Key

For developers investigating, use the api_key from the companies table you're currently investigating.

Step 3: Update Claude Desktop Configuration

On macOS, the configuration file is located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Open the file and add the MCP server configuration:

{
  "mcpServers": {
    "storage-essentials": {
      "command": "npx",
      "args": ["@golocalinteractive/storage-essentials-mcp"],
      "env": {
        "SE_API_KEY": "your_actual_api_key_here",
        "SE_ENVIRONMENT": "staging"
      }
    }
  }
}

Important:

• Replace /Users/{user}/Projects/hack/claude/se-mcp with the actual absolute path to your project
• Replace your_actual_api_key_here with your real API key
• Set SE_ENVIRONMENT to local, staging, or production

Step 4: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Step 5: Verify Installation

In Claude Code, you should now see the Storage Essentials MCP tools available. Try a simple test:

Can you list the available Storage Essentials facilities?

This will use the seV2FacilitiesList tool.

Troubleshooting

Problem: Tools not appearing

• Verify the path in the config is absolute and correct
• Check that build/index.js exists in your project directory
• Ensure Claude Desktop was fully restarted (not just window closed)

Problem: Authentication errors

• Verify your SE_API_KEY is correct
• Check the SE_ENVIRONMENT matches where your API key is valid
• Look at Claude Desktop logs for detailed error messages

Problem: "Command not found" or similar errors

• Make sure you ran npm run build successfully
• Check that node is available in your PATH
• Verify the shebang (#!/usr/bin/env node) is at the top of build/index.js

Viewing Logs

Claude Desktop logs can help debug issues:

• macOS: ~/Library/Logs/Claude/

Project Structure

src/
  index.ts          # Main MCP server entry point
  types.ts          # TypeScript type definitions
  auth.ts           # Authentication manager
  utils.ts          # Utility functions
  v2/
    base.ts         # Base class for V2 operations
    index.ts        # V2 API endpoint handlers

API Versioning

• V2 API: Uses Accept header application/vnd.storageessentials.v2+json
• RESTful endpoints under /api/* prefix
• Bearer token authentication with automatic refresh

Authentication Flow

1. Server initializes with SE_API_KEY from environment
2. First API call triggers automatic authentication via /login endpoint
3. Token is cached and automatically refreshed before expiry
4. All subsequent requests use the cached Bearer token

Error Handling

The server provides detailed error messages for:

• Missing required parameters
• Authentication failures
• API request errors
• Invalid tool names

Errors are returned in the format:

{
  "content": [{ "type": "text", "text": "Error: <error message>" }],
  "isError": true
}

License

MIT

Support

For issues or questions, please refer to the Storage Essentials API documentation or contact support.