MCP Lightcast

Lightcast’s labor-market intelligence, connected to your AI tools.

Documentation · Tool reference · PyPI · v0.4.0 release notes

37 MCP tools for Skills, Titles, Classification, Similarity, Occupation Benchmark, Career Pathways, US Job Postings, and Core LMI. Built with Python 3.14+, FastMCP 4, and scope-specific OAuth authentication.

Install v0.4.0

Version 0.4.0 is available on PyPI and requires Python 3.14 or newer. With uv installed, run the published package without cloning this repository:

uvx --python 3.14 mcp-lightcast@0.4.0 --version

Alternatively, install into an existing Python 3.14+ virtual environment with python -m pip install "mcp-lightcast==0.4.0", then use the mcp-lightcast command directly.

Upgrading from 0.2? Review the migration guide for the higher Python requirement, default stdio transport, and breaking Skills, Job Postings, and Occupation Benchmark tool changes.

Configure your credentials

Create a local .env file containing:

LIGHTCAST_CLIENT_ID=your-client-id
LIGHTCAST_CLIENT_SECRET=your-client-secret

Get Lightcast credentials. Free-tier accounts may need LIGHTCAST_OAUTH_SCOPE=lightcast_open_free. Premium endpoints require their own permissions and quotas.

From the directory containing .env, check authentication and start the server:

uvx --python 3.14 mcp-lightcast@0.4.0 --env-file .env --validate-config
uvx --python 3.14 mcp-lightcast@0.4.0 --env-file .env --transport stdio

The authentication check validates the default scope; it does not establish access to every API or Core LMI dataset.

Connect your MCP client

For a client that launches local MCP servers, use the following configuration. Replace the environment-file path with your own absolute path; no repository checkout is needed. If your client cannot find uvx, use its absolute executable path.

{
  "mcpServers": {
    "lightcast": {
      "command": "uvx",
      "args": [
        "--python", "3.14", "mcp-lightcast@0.4.0",
        "--env-file", "/absolute/path/to/lightcast.env",
        "--transport", "stdio", "--quiet"
      ]
    }
  }
}

For HTTP:

uvx --python 3.14 mcp-lightcast@0.4.0 --env-file .env \
  --transport streamable-http --host 127.0.0.1 --port 3000

Connect to http://127.0.0.1:3000/mcp. Keep HTTP local or use an authenticated gateway; inbound MCP authentication is not built in.

Available since v0.3.1, GET /health returns {"status":"ok"} without contacting Lightcast; HEAD is also supported. See the health and reverse proxy guide for monitoring and the nginx configuration tested with HTTPS, path prefixes, and both MCP protocol versions.

Docker

The published image includes Python and the server:

docker run --rm -i --platform linux/amd64 --env-file .env \
  ghcr.io/lawwu/mcp-lightcast:0.4.0

The image targets Linux amd64; Docker can emulate it on Apple Silicon. Moving tags 0.4 and latest are also available. See deployment for HTTP hosting.

What you can do

New in v0.4.0: credential providers keep environment credentials as the default for local use and add optional HTTP credential headers, account-isolated token caches, and a custom provider interface for authorized secret-store integrations. Header mode never falls back to the server’s environment account. Shared HTTP deployments still need inbound MCP authentication.

Use metadata tools to discover fields and supported versions. Workflows preserve IDs, provenance, warnings, and partial failures. They never invent benchmark or career results.

Core LMI support

New in v0.3.0, Core LMI (Agnitio) provides employment, earnings, industry, education, and regional measures. It uses your existing Lightcast credentials and automatically requests the separate agnitio scope. Your Lightcast license determines which datasets you can query.

Try asking your assistant:

• “Compare software developer employment and median annual earnings in California and Washington.”
• “How many restaurant jobs are in King and Kitsap counties combined, and how concentrated is the industry locally?”
• “How many computer science bachelor's awards did UW Seattle report?”

Start with dataset discovery, inspect the release and metadata, then query using the returned codes. Core LMI describes labor-market measures and projections; Job Postings describes advertised demand.

The release review passed 18 live Core LMI checks against occupation, industry, and education-completions data. The tested account exposed 52 datasets; that catalog is account-specific. See the Core LMI guide for verified JSON examples, pagination limits, and the known cost-of-living query limitation, and the API review for test details.

Develop and test

To work on the source:

git clone https://github.com/lawwu/mcp-lightcast.git
cd mcp-lightcast
uv sync --python 3.14 --all-groups --frozen
cp .env.example .env             # Add credentials only for live API use
uv run pytest                    # Offline by default; no API credentials needed
uv run ruff check src tests
uv run mypy src
uv run --group docs python scripts/docs.py serve # Local docs with live reload

Explicit live checks:

uv run pytest --live -m live
uv run python -m mcp_lightcast.diagnostics --operations --output test-results/live.json
uv run python -m mcp_lightcast.diagnostics --core-lmi --output test-results/core-lmi.json

Both diagnostic commands consume real API quotas. Their reports contain only tool outcomes and version metadata.

Dependency updates

Dependabot patch and minor updates are eligible for automatic squash merge after required checks pass. Major updates remain for manual review. See dependency maintenance for the policy and required repository settings.

Documentation deployment

The docs use Zensical with custom styling, search, light/dark themes, and a tool reference generated from actual MCP schemas. GitHub Actions builds pull requests and deploys main to GitHub Pages. Set Settings → Pages → Source → GitHub Actions once. No Lightcast secrets are needed for documentation builds.

See deployment, configuration, and the 0.3 migration guide. This is an independent MIT-licensed project, not an official Lightcast product.