altsportsdata-catalog-mcp

Model Context Protocol (MCP) server for the AltSportsData Data Catalog API. It exposes catalog discovery, table metadata, filtered row reads, and cross-schema resource queries so Claude (or other MCP clients) can answer questions against the catalog using your company password.

Public API docs: https://catalog-api.altsportsleagues.ai/docs

npm in this monorepo (read this)

The repo root uses npm workspaces, and several clients/* packages share the same package.json name. npm then fails before any command runs (must not have multiple workspaces with the same name). So from apps/altsportsdata-data-catalog-api-mcp-typescript/ you cannot use npm install, npm run, or npm publish — use the helper scripts below (they copy this package to a temp directory where npm is sane).

| Goal | Command | |------|---------| | Publish to npm | ./pub or ./scripts/publish-npm.sh (add --dry-run to test) | | Local dev (stdio MCP) | export DATA_CATALOG_PASSWORD=… then ./scripts/dev-isolated.sh |

## Use with Claude via npmjs

After this package is published on npm, Claude (Desktop or any MCP client) runs it from the registry—you do not need this repo on disk.

1. Publish (maintainers only)

Do not run npm publish in this folder. From apps/altsportsdata-data-catalog-api-mcp-typescript/:

./pub
# same as: ./scripts/publish-npm.sh

2. Install / run for end users

Either global CLI:

npm install -g altsportsdata-catalog-mcp

Or let the MCP launcher fetch it (recommended with npx):

npx -y altsportsdata-catalog-mcp

3. Claude Desktop

1. Quit Claude Desktop.
2. Edit the config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Merge this under the top-level object (add or merge mcpServers):

{
  "mcpServers": {
    "altsportsdata-catalog": {
      "command": "npx",
      "args": ["-y", "altsportsdata-catalog-mcp"],
      "env": {
        "DATA_CATALOG_PASSWORD": "your-shared-password-here"
      }
    }
  }
}

4. Start Claude Desktop again. Under Settings → Developer you should see the server; enable it if needed.

npx -y pulls altsportsdata-catalog-mcp from npmjs on first use; Node 18+ required.

4. Cursor / other MCP hosts

Same mcpServers block: in Cursor this usually lives in .cursor/mcp.json (project) or user MCP settings—same command / args / env as above.

Environment

| Variable | Required | Notes | |----------|----------|--------| | DATA_CATALOG_PASSWORD | Yes | Shared catalog password (same as server DATA_CATALOG_PASSWORD) | | DATA_CATALOG_BASE_URL | No | Default https://catalog-api.altsportsleagues.ai |

Tools (21 total)

Catalog

| Tool | Purpose | |------|---------| | catalog_health | Health + DB configured flag | | catalog_about | Service description and capabilities | | catalog_list_schemas | All schemas and table names | | catalog_get_schema | Tables and columns for one schema | | catalog_get_table | Columns for one table | | catalog_list_table_rows | Paginated/filtered rows for a table | | catalog_table_stats | Aggregate column statistics (min, max, distinct, non-null) | | catalog_list_queryable_resources | Logical resources (events, sessions, ...) | | catalog_query_resource | Query a resource across one or all schemas |

Ask (Claude-powered NL)

| Tool | Purpose | |------|---------| | ask_question | NL question → Redshift SQL → results + summary | | ask_graphql | NL question → GraphQL → results + summary |

GraphQL

| Tool | Purpose | |------|---------| | graphql_query | Execute a raw GraphQL query | | graphql_schema | Introspect the GraphQL schema |

Datasets

| Tool | Purpose | |------|---------| | catalog_dataset_manifest | List curated golden datasets | | catalog_dataset | Load a golden dataset by name |

Redshift

| Tool | Purpose | |------|---------| | redshift_examples | Get example Redshift analytics queries | | redshift_sql | Get full SQL for a specific example query | | redshift_execute_sql | Execute a read-only SQL query against Redshift |

Query History

| Tool | Purpose | |------|---------| | query_history | Recent user-submitted queries (newest first) | | query_seeds | Pre-verified example queries for exploration |

Resource

• catalog://openapi — OpenAPI JSON (/openapi.json) for full request/response shapes.

Auth

The HTTP API accepts the password via X-Data-Catalog-Password (what this package sends). The server also supports Bearer or Basic auth; see the API’s OpenAPI/security description.

Develop (inside this monorepo)

Plain npm install / npm run dev in this directory will fail (workspace error). Use:

cd apps/altsportsdata-data-catalog-api-mcp-typescript
export DATA_CATALOG_PASSWORD="your-password"
./scripts/dev-isolated.sh

License

MIT