@stqry/mcp-server

MCP server for the STQRY Builder API. Auto-generates tools from the STQRY OpenAPI spec, letting LLMs (Claude, ChatGPT, etc.) manage tours, screens, collections, media, and more through natural language.

Features

• 66 API tools auto-generated from the STQRY OpenAPI spec
• Multi-project support — switch between STQRY projects mid-session
• 4 regions — US, Canada, EU, Australia
• LLM-friendly descriptions for key tools
• stdio transport for use with Claude Desktop, Cursor, and other MCP clients

Prerequisites

• Node.js >= 18
• A STQRY Builder API key (one per project)

Installation

npm install
npm run build

Configuration

Create ~/.stqry-mcp.json:

{
  "projects": {
    "museum-of-art": {
      "apiKey": "your-api-key",
      "region": "us",
      "description": "Museum of Art production"
    },
    "history-center": {
      "apiKey": "another-api-key",
      "region": "eu",
      "description": "History Center staging"
    }
  },
  "defaultProject": "museum-of-art"
}

| Field | Required | Description | |-------|----------|-------------| | projects | Yes | At least one project | | projects.*.apiKey | Yes | STQRY API key (X-Api-Token header) | | projects.*.region | Yes | us, ca, eu, or au | | projects.*.description | No | Human-readable label | | defaultProject | No | Must match a project key if set |

Regions

| Region | API Base URL | |--------|-------------| | us | https://api-us.stqry.com | | ca | https://api-ca.stqry.com | | eu | https://api-eu.stqry.com | | au | https://api-au.stqry.com |

Usage

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "stqry": {
      "command": "node",
      "args": ["/absolute/path/to/stqry-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "stqry": {
      "command": "node",
      "args": ["/absolute/path/to/stqry-mcp/dist/index.js"]
    }
  }
}

Direct (stdio)

node dist/index.js

MCP Inspector

Debug and explore available tools:

npm run inspect

Tools

Project Management

| Tool | Description | |------|-------------| | stqry_list_projects | List all configured projects and show which is active | | stqry_switch_project | Switch the active project for subsequent API calls |

API Tools

Tools follow the naming convention stqry_{resource}_{action}. Key resources:

| Resource | Actions | Description | |----------|---------|-------------| | screens | list, get, create, update, delete | Tour stops, exhibits, POIs | | collections | list, get, create, update, delete | Tours, lists, menus | | collection_items | list, create, update, delete, update_positions | Items within collections | | story_sections | list, create, update, delete, update_positions | Content blocks within screens | | media_items | list, get, create, update, delete | Images, audio, video, AR models | | codes | list, get, create, update, delete | Promotional/access codes | | uploaded_files | list, presigned | File uploads via S3 presigned URLs | | projects | get | Project details |

Sub-item resources for story sections: story_section_badge_items, story_section_link_items, story_section_media_items, story_section_opening_time_items, story_section_price_items, story_section_social_items.

All tools include path parameters as required inputs and query parameters as optional inputs. Tools that modify data accept a body object with the request payload.

Development

npm run dev          # Watch mode (recompile on change)
npm test             # Run tests
npm run test:watch   # Watch mode tests
npm run build        # Production build

Project Structure

src/
├── index.ts                  # Entry point, stdio transport
├── server.ts                 # MCP server setup & tool routing
├── config/loader.ts          # Config loading & Zod validation
├── openapi/
│   ├── parser.ts             # OpenAPI spec → MCP tool generation
│   └── overrides.ts          # LLM-friendly description overrides
├── client/stqry-client.ts    # HTTP client for STQRY API
├── tools/project-tools.ts    # Project list/switch tools
└── types/index.ts            # Shared TypeScript types
spec/
└── stqry-openapi.json        # Bundled OpenAPI 3.1.0 spec

License

Proprietary — STQRY.