How do I use mcp-lightcast?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-lightcast Extract skills from: Senior Python developer with Django" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-lightcast

by lawwu

Overview Schema Source Related Servers Discussions Admin

Python

Remote

MCP Lightcast

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

Documentation · Tool reference · PyPI · v0.4.1 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.1

Version 0.4.1 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.1 --version

Alternatively, install into an existing Python 3.14+ virtual environment with python -m pip install "mcp-lightcast==0.4.1", 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.1 --env-file .env --validate-config
uvx --python 3.14 mcp-lightcast@0.4.1 --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.1",
        "--env-file", "/absolute/path/to/lightcast.env",
        "--transport", "stdio", "--quiet"
      ]
    }
  }
}

For HTTP:

uvx --python 3.14 mcp-lightcast@0.4.1 --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.1

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.

Related MCP server: mcp-onet

What you can do

Available since 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.

Task	Tools
Search, retrieve, and extract skills	`search_skills`, `get_skill_details`, `bulk_retrieve_skills`, `extract_skills_from_text`
Normalize job titles	`search_job_titles`, `normalize_job_title`, `get_job_title_details`
Classify and map occupations	`classify_occupation`, `list_taxonomy_mappings`, `map_taxonomy_concepts`
Compare skills and careers	`query_similarity`, `get_career_next_steps`, `get_career_skill_gap`
Investigate demand and pay	`search_job_postings`, `get_posting_statistics`, `get_posting_rankings`, `get_occupation_benchmark`
Explore employment, wages, and education	Core LMI tools below
Combine APIs	`normalize_title_and_get_skills`, `analyze_job_posting_skills`

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.

Tool	Purpose
`list_core_lmi_datasets`	Discover the datasets available to your account
`get_core_lmi_versions`	Find available releases for a dataset
`get_core_lmi_metadata`	Inspect measures, dimensions, and query capabilities
`get_core_lmi_dimension`	Look up valid occupation, industry, region, or institution codes
`query_core_lmi`	Query measures, combine regions, and calculate location quotients or shift-share components where supported

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.

Available Tools

37 tools

analyze_job_posting_skillsAnalyze Job Posting SkillsB

Read-onlyIdempotent

Normalize a title and extract skills explicitly present in its title/description. Does not infer occupation skills. version controls Titles; skills_version controls Skills.

Inputs: job_title (required), job_description (required), version, skills_version, +2 more. Returns: object

bulk_retrieve_skillsBulk Retrieve SkillsC

Read-onlyIdempotent

Retrieve multiple skills in one request.

Inputs: skill_ids (required), version. Returns: result

bulk_retrieve_titlesBulk Retrieve TitlesC

Read-onlyIdempotent

Retrieve multiple titles in one request.

Inputs: title_ids (required), version. Returns: result

classify_occupationClassify OccupationC

Read-onlyIdempotent

Classify a title and optional description to LOT specialized occupations. May consume a limited classifier quota.

Inputs: title (required), limit, version, description, +1 more. Returns: object

extract_skills_from_textExtract Skills From TextB

Read-onlyIdempotent

Extract explicitly mentioned skills from text. Requires extraction permission and may consume a limited quota.

Inputs: text (required), version, confidence_threshold. Returns: result

find_similar_skillsFind Similar SkillsC

Read-onlyIdempotent

Find scored similar skills. Requires the separate Similarity API subscription.

Inputs: skill_id (required), limit. Returns: object

get_benchmark_metadataGet Benchmark MetadataA

Read-onlyIdempotent

Discover benchmark dimensions, available datasets, regions, and taxonomy versions.

Inputs: no named parameters. Returns: object

get_career_next_stepsGet Career Next StepsC

Read-onlyIdempotent

Find potential next occupations from the Career Pathways model. Discover available categories in metadata.

Inputs: occupation_id (required), limit, nation, dimension, +2 more. Returns: object

get_career_skill_gapGet Career Skill GapB

Read-onlyIdempotent

Compare source and destination occupations within the same taxonomy to identify skill gaps.

Inputs: source_id (required), destination_id (required), limit, nation, +2 more. Returns: object

get_classification_metadataGet Classification MetadataA

Read-onlyIdempotent

Get source types for an active classifier release. latest discovers the newest nonexpired release.

Inputs: version. Returns: object

get_core_lmi_dimensionGet Core Lmi DimensionA

Read-onlyIdempotent

Find valid dimension codes by name/code search, or browse a hierarchy using level and aggregation_path. Search and hierarchy filters are separate modes. Use returned child codes exactly, including leading zeros; metadata pagination is local.

Inputs: dataset (required), dimension (required), level, limit, +4 more. Returns: items, dataset, version, dimension, +1 more

get_core_lmi_metadataGet Core Lmi MetadataA

Read-onlyIdempotent

Inspect a Core LMI release's attributes, dimensions and available metrics before querying. Filter metrics by substring (e.g. Jobs. or Earnings); follow metrics_pagination.next_offset. Release version is different from metric year.

Inputs: dataset (required), limit, offset, version, +1 more. Returns: metrics, attributes, dimensions, datasetName, +2 more

get_core_lmi_versionsGet Core Lmi VersionsB

Read-onlyIdempotent

List releases for an accessible Core LMI dataset. latest_numeric is discovered numerically, never taken from array order. Pin a returned release for reproducible queries; base/example require explicit selection.

Inputs: dataset (required). Returns: dataset, versions, latest_numeric

get_job_posting_detailsGet Job Posting DetailsA

Read-onlyIdempotent

Retrieve a US posting by ID. Requires posting-detail permissions.

Inputs: posting_id (required). Returns: object

get_job_title_detailsGet Job Title DetailsC

Read-onlyIdempotent

Retrieve a standardized title by its Lightcast ID.

Inputs: title_id (required), version. Returns: object

get_occupation_benchmarkGet Occupation BenchmarkB

Read-onlyIdempotent

Benchmark a LOT occupation. metrics are dataset names (salary, demand, specializedSkills, etc.); region is {"nation": "us"}. Preserves warnings about unavailable datasets.

Inputs: occupation_id (required), region, metrics, dimension, +1 more. Returns: object

get_pathways_metadataGet Pathways MetadataB

Read-onlyIdempotent

Discover career-pathway dimensions, categories, nations, and taxonomy versions.

Inputs: no named parameters. Returns: object

get_posting_rankingsGet Posting RankingsB

Read-onlyIdempotent

Rank a facet such as skills_name or company_name by unique US postings. filters.when is required.

Inputs: facet (required), filters (required), limit. Returns: object

get_postings_metadataGet Postings MetadataA

Read-onlyIdempotent

Discover accessible US posting fields, filters, metrics, and available months.

Inputs: no named parameters. Returns: object

get_posting_statisticsGet Posting StatisticsA

Read-onlyIdempotent

Get US posting totals; metrics default to unique_postings. filters.when is required. Discover filters and metrics in metadata.

Inputs: filters (required), metrics. Returns: object

get_related_skillsGet Related SkillsC

Read-onlyIdempotent

Find related skills using the Skills API. Results are related skills, not scored Similarity mappings.

Inputs: skill_id (required), limit, version. Returns: result

get_similarity_metadataGet Similarity MetadataA

Read-onlyIdempotent

Discover Similarity models and the taxonomy versions they accept.

Inputs: no named parameters. Returns: object

get_skill_detailsGet Skill DetailsC

Read-onlyIdempotent

Get a skill by its Lightcast ID.

Inputs: skill_id (required), version. Returns: object

get_skills_metadataGet Skills MetadataB

Read-onlyIdempotent

Discover the Skills taxonomy version, supported fields, and skill types.

Inputs: version. Returns: object

get_titles_metadataGet Titles MetadataB

Read-onlyIdempotent

Discover the current Titles taxonomy version and available fields.

Inputs: version. Returns: object

list_classification_releasesList Classification ReleasesA

Read-onlyIdempotent

List classifier releases, removal dates, and supported taxonomy versions.

Inputs: no named parameters. Returns: result

list_core_lmi_datasetsList Core Lmi DatasetsA

Read-onlyIdempotent

Discover Core LMI datasets and releases accessible to your account (agnitio scope). Optionally include descriptions and filter by name/text. Follow pagination.next_offset; metadata pagination is local after one upstream fetch.

Inputs: limit, query, offset, include_definitions. Returns: datasets, pagination

list_taxonomy_mappingsList Taxonomy MappingsA

Read-onlyIdempotent

Discover mapping names and source/destination taxonomy versions; do this before mapping IDs.

Inputs: no named parameters. Returns: result

map_taxonomy_conceptsMap Taxonomy ConceptsA

Read-onlyIdempotent

Map concept IDs using a mapping name returned by list_taxonomy_mappings.

Inputs: ids (required), mapping_name (required). Returns: object

normalize_job_titleNormalize Job TitleB

Read-onlyIdempotent

Normalize a raw job title, with confidence. Requires normalization permission; may consume a limited quota.

Inputs: title (required), version. Returns: object

normalize_title_and_extract_skillsNormalize Title And Extract SkillsB

Read-onlyIdempotent

Normalize a title and extract explicitly mentioned skills using the current Classification release. May consume two classifier quota requests.

Inputs: title (required), version, confidence_threshold. Returns: object

normalize_title_and_get_skillsNormalize Title And Get SkillsA

Read-onlyIdempotent

Normalize a title, classify to LOT specialized occupations, then retrieve associated skills from Similarity. Requires three API permissions. Reports partial failures; version controls Titles only, classification_version controls classifiers, and lot_version must match the classifier's LOT major version.

Inputs: raw_title (required), version, skill_type, lot_version, +4 more. Returns: object

query_core_lmiQuery Core LmiA

Read-onlyIdempotent

Query employment, wages, education or other Core LMI measures using discovered metrics and dimension codes. Read-only POST; consumes quota. Supports named aggregations, mapLevel, LocationQuotient, ShiftShare, sorting and bounded pagination (100 rows default, 500 maximum per page, first 5000 rows accessible). data is column-oriented: combine values at matching row indices. Preserve returned version and upstream metadata; missing/suppressed values are not zero. Use sortBy for repeatable pages. Offset is applied locally to a bounded prefix because the service ignores native offset. Follow pagination.next_offset; narrow the query if has_more is true at window_limit. totalRows is upstream metadata, not a grand total.

Inputs: query (required), dataset (required), version. Returns: data, errors, dataset, timings, +3 more

query_similarityQuery SimilarityC

Read-onlyIdempotent

Query a Similarity model, e.g. soc, skill, lotspecocc-skill, or skill-lotocc. Only skill-input models accept a list. Preserves upstream warnings.

Inputs: input (required), model (required), limit, min_score, +2 more. Returns: object

search_job_postingsSearch Job PostingsA

Read-onlyIdempotent

Search US postings with native filters including required when (active or a start/end range), e.g. {"when": "active", "title": ["ET6850661D6AE5FA86"], "city_name": ["Seattle, WA"]}. Use metadata to discover filters; requires postings:us.

Inputs: filters (required), page, limit, fields. Returns: object

search_job_titlesSearch Job TitlesB

Read-onlyIdempotent

Search standardized job titles. version is a Titles taxonomy version or latest.

Inputs: query (required), limit, version. Returns: result

search_skillsSearch SkillsB

Read-onlyIdempotent

Search the Skills taxonomy. skill_type accepts type IDs: ST1 (specialized), ST2 (common), ST3 (certification), comma-separated.

Inputs: query (required), limit, version, skill_type. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored 2026-11-14 16:20 across 37 tools

Disambiguation4/5

Most tools map cleanly to a distinct resource and action (skills, titles, postings, LMI, similarity, pathways), and descriptions explicitly clarify subtle boundaries such as related vs. similar skills. The main ambiguity is among the three composite pipeline tools (normalize_title_and_get_skills, normalize_title_and_extract_skills, analyze_job_posting_skills), which overlap in workflow and could still be misselected.

Naming Consistency5/5

Tool names consistently use snake_case with a predictable verb_noun pattern (search_skills, get_skill_details, query_core_lmi, map_taxonomy_concepts). Longer composite names remain readable and follow the same convention.

Tool Count3/5

The 37 tools span roughly eight distinct Lightcast sub-APIs (Skills, Titles, Postings, Classification, Similarity, Core LMI, Benchmarks, Pathways), so many tools are justified. However, the count is heavy, and the redundant composite workflow tools push it beyond a comfortably scoped surface.

Completeness5/5

The surface covers discovery/metadata, search, detail retrieval, bulk retrieval, mapping, classification, benchmarking, and cross-API composites for every major taxonomy and dataset. Since the APIs are read-only analytics services, there are no obvious missing create/update/delete lifecycle operations.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

DEWEY SOC codes classifier.
io.github.scoutexchange
Classification service to seamlessly retrieve SOC codes for job titles and descriptions.
Search Government Data Research & Data
2
https://dewey-lro-test.lro.goscoutgo.com/mcp
CareeronestopB
io.github.pipeworx-io
CareerOneStop MCP — wraps the CareerOneStop Web API (U.S. Dept. of Labor) (api.careeronestop.org).…
Education & Learning Tools Government Data
471
https://gateway.pipeworx.io/careeronestop/mcp
Norvstar — Professional Identity MCP Server
com.norvstar
Query professional profiles, search candidates, and get AI-powered summaries and job fit analysis.
Search Research & Data Marketing
2
https://norvstar.com/api/mcp
Job Post Enricher: Salary, Seniority, Remote, Visa & Skills
io.github.Nero-Engine
AI salary, seniority, remote, visa and skills fields for LinkedIn, Indeed or any jobs dataset.
Research & Data AI & Machine Learning
1
https://mcp.apify.com/?tools=nerolabs/job-post-enricher

Related MCP Servers

mcp-careeronestop
Government Data Open Data
pipeworx-io
A
license
Not graded
quality
B
maintenance
Enables querying U.S. Dept. of Labor CareerOneStop data for occupations, salaries, and salary comparisons across locations.
Updated 6 days ago (2026-11-09 13:38 UTC)
94 npm
MIT
mcp-onet
Government Data Research & Data Search
pipeworx-io
A
license
Not graded
quality
B
maintenance
Enables querying the O*NET occupation taxonomy, including keyword search, occupation details, skills, and associated tools and technology.
Updated 6 days ago (2026-11-09 14:27 UTC)
96 npm
MIT
LAPRAS MCP Server
Search
TorstenThompson21
F
license
Not graded
quality
B
maintenance
Enables AI assistants to search job listings and retrieve or update a user's career profile, including work experiences, job summaries, career goals, and technical skills through natural language.
Updated a month ago (2026-10-16 10:07 UTC)
-
LAPRAS MCP Server
Search
yasminegiordano487
F
license
Not graded
quality
A
maintenance
Enables AI assistants to search and retrieve job listings, and to read or manage career profile data such as work history, job summaries, career goals, and technical skills.
Updated a month ago (2026-10-17 10:22 UTC)
-

MCP Lightcast

Install v0.4.1

Configure your credentials

Connect your MCP client

Docker

What you can do

Core LMI support

Develop and test

Dependency updates

Documentation deployment

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-careeronestop

mcp-onet

LAPRAS MCP Server

LAPRAS MCP Server