# Mcp Lightcast

> MCP Server for Lightcast API

- **Type:** MCP server
- **Install:** `agentstack add mcp-lawwu-mcp-lightcast`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lawwu](https://agentstack.voostack.com/s/lawwu)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lawwu](https://github.com/lawwu)
- **Source:** https://github.com/lawwu/mcp-lightcast

## Install

```sh
agentstack add mcp-lawwu-mcp-lightcast
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Lightcast Server

[](https://pypi.org/project/mcp-lightcast/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/lawwu/mcp-lightcast/actions)

A production-ready Model Context Protocol (MCP) server that provides seamless integration with Lightcast APIs for job titles, skills analysis, and career data. Built with FastMCP and modern Python development practices.

**🎯 Current Status: v0.2.1**

## 🚀 Features

### ✅ **Working APIs & Endpoints**

#### **🎯 Skills API (9/9 endpoints)** - Version 9.33, 41,139 skills
- ✅ **Skills Search** - Search with filters (type, category, subcategory)
- ✅ **Individual Skill Retrieval** - Get detailed skill information by ID
- ✅ **Skills Extraction from Text** - Extract skills from job descriptions with confidence scores
- ✅ **Bulk Skills Retrieval** - Efficient batch processing of multiple skills
- ✅ **Related Skills** - Find skills related to a specific skill (POST endpoint working)
- ✅ **Similar Skills** - Find similar skills via Similarity API
- ✅ **Skill Types** - Get all available skill types
- ✅ **Version Metadata** - Complete API version and statistics information
- ✅ **Skills Metadata** - General skills taxonomy information

#### **🏷️ Titles API (8/8 endpoints)** - Version 5.47, 73,993 titles
- ✅ **Job Title Search** - Search Lightcast's comprehensive job title database
- ✅ **Individual Title Retrieval** - Get detailed title information by ID
- ✅ **Bulk Title Retrieval** - Efficient batch processing of multiple titles
- ✅ **Title Normalization** - Normalize raw job titles
- ✅ **Title Hierarchy** - Get hierarchical structure for titles
- ✅ **Version Metadata** - Complete API version and statistics information
- ✅ **General Metadata** - Latest version and attribution information
- ✅ **Full Metadata** - Comprehensive taxonomy information

#### **🔄 Classification API (5/5 endpoints)** - Version 2025.8
- ✅ **Skills Extraction** - Extract skills from text using classification models
- ✅ **Available Versions** - Get all available API versions
- ✅ **Version Metadata** - Detailed version information
- ✅ **Skill Normalization** - Normalize skill text via extraction
- ✅ **Title Normalization** - Normalize title text with fallback

#### **🔗 Similarity API (7/7 endpoints)** - Premium Features
- ✅ **Available Models** - Get all similarity models
- ✅ **API Metadata** - Similarity API capabilities
- ✅ **Occupation Skills** - Skills associated with occupations
- ✅ **Similar Occupations** - Find similar occupations
- ✅ **Similar Skills** - Find similar skills
- ✅ **SOC Model** - Direct SOC similarity queries
- ✅ **Skill Model** - Direct skill similarity queries

#### **📊 Occupation Benchmark API (6/6 endpoints)** - Premium Features
- ✅ **API Metadata** - Benchmark API capabilities
- ✅ **Available Areas** - Geographic areas available
- ✅ **Available Metrics** - All available benchmark metrics
- ✅ **Benchmark Data** - Salary and employment data
- ✅ **SOC Dimension** - SOC code dimension data
- ✅ **LOT Dimension** - LOT occupation dimension data

#### **🛤️ Career Pathways API (3/3 endpoints)** - Premium Features
- ✅ **API Metadata** - Career pathways capabilities
- ✅ **Available Dimensions** - Pathway analysis dimensions
- ✅ **Pathway Analysis** - Career transition analysis

#### **💼 Job Postings API (3/3 endpoints)** - Premium Features
- ✅ **Available Facets** - Job posting search facets
- ✅ **Postings Summary** - Job posting trends and statistics
- ✅ **Top Skills** - Most in-demand skills from job postings

#### **🔄 Workflow Integration (2/2 endpoints)** - Custom Workflows
- ✅ **Title → Skills Workflow** - Complete title normalization and skills extraction
- ✅ **Simple Title Skills** - Streamlined title-to-skills pipeline

### 🔧 **Core Functionality
- **🎯 Skills Extraction from Text** - High accuracy skill identification from job descriptions
- **📊 Search & Discovery** - Fast, filtered search across skills, titles, and job postings
- **⚡ Bulk Operations** - Efficient processing of multiple items in single requests
- **🔄 Version Management** - Uses "latest" keyword with backward compatibility
- **🔐 OAuth2 Authentication** - Secure authentication with dynamic scope switching
- **🔗 Related & Similar Skills** - Find skills relationships via multiple APIs
- **💼 Job Market Data** - Real-time job posting analysis and trends
- **📊 Benchmarks & Analytics** - Salary and employment data access
- **🛤️ Career Pathways** - Career transition analysis and recommendations

### 🛠️ **MCP Tools Available (23 core tools across 7 categories)**

#### **Skills Tools (7 tools)**
API Docs: https://docs.lightcast.dev/apis/skills

- `bulk_retrieve_skills` - Efficient bulk skill retrieval
- `extract_skills_from_text` - Extract skills with custom confidence threshold
- `find_similar_skills` - Find similar skills via Similarity API
- `get_skill_details` - Get detailed skill information by ID
- `get_skills_metadata` - General skills taxonomy metadata
- `get_related_skills` - Find skills related to a specific skill (now working with POST endpoint)
- `search_skills` - Search skills with advanced filters (type, category, subcategory)

#### **Titles Tools (4 tools)**
API Docs: https://docs.lightcast.dev/apis/titles

- `bulk_retrieve_titles` - Efficient bulk title retrieval
- `get_job_title_details` - Get detailed title information by ID
- `normalize_job_title` - Normalize raw job titles
- `search_job_titles` - Search job titles in Lightcast database

#### **Job Postings Tools (3 tools)**
API Docs: https://docs.lightcast.dev/apis/job-postings

- `get_job_posting_details` - Get detailed job posting information
- `get_posting_statistics` - Job posting trends and analytics
- `search_job_postings` - Search real-time job market data

#### **Classification Tools (1 tool)**
API Docs: https://docs.lightcast.dev/apis/classification

- `get_classification_metadata` - Classification API capabilities and metadata

#### **Occupation Benchmark Tools (2 tools)**
API Docs: https://docs.lightcast.dev/apis/occupation-benchmark

- `get_benchmark_metadata` - Benchmark API capabilities and metadata
- `get_occupation_benchmark` - Salary and employment benchmarks by occupation

#### **Similarity Tools (3 tools)**
API Docs: https://docs.lightcast.dev/apis/similarity

- `get_similarity_metadata` - Similarity API capabilities and metadata
- `get_pathways_metadata` - Career pathways API capabilities and metadata

#### **Unified Workflows (4 tools)**
- `analyze_job_posting_skills` - Comprehensive job posting analysis
- `normalize_title_and_get_skills` - Complete title→skills workflow
- `normalize_title_and_extract_skills` - Alternative classification-based extraction

## 🛠️ Installation

### Prerequisites

- Python 3.12+ (required for uv-dynamic-versioning)
- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
- Lightcast API credentials (Client ID and Secret with `emsi_open` scope). You can request free API access [here](https://lightcast.io/open-skills/access) which will give you access to the skills and titles taxonomies (subset of only the Skills and Titles APIs).

### 🚀 Quick Start with uvx (Recommended)

```bash
# Install and run directly from PyPI (no installation required)
uvx --from mcp-lightcast mcp-lightcast --help

# Run with environment variables
LIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \
uvx --from mcp-lightcast mcp-lightcast

# Use stdio transport for Claude Desktop
LIGHTCAST_CLIENT_ID=your_id LIGHTCAST_CLIENT_SECRET=your_secret \
uvx --from mcp-lightcast mcp-lightcast --transport stdio
```

### 📦 Install from PyPI

```bash
# Install globally
pip install mcp-lightcast

# Or with uv
uv tool install mcp-lightcast

# Run the server
mcp-lightcast --help
```

### 🔧 Development Installation

```bash
# 1. Clone the repository
git clone https://github.com/lawwu/mcp-lightcast.git
cd mcp-lightcast

# 2. Set up development environment 
make setup

# 3. Configure your API credentials
# Edit .env with your Lightcast API credentials

# 4. Validate configuration
make validate-config

# 5. Run the server
make run
```

### 🐳 Docker Installation

```bash
# Pull the latest image (when available)
docker pull ghcr.io/lawwu/mcp-lightcast:latest

# Run with environment variables
docker run --rm -it \
  -e LIGHTCAST_CLIENT_ID=your_id \
  -e LIGHTCAST_CLIENT_SECRET=your_secret \
  ghcr.io/lawwu/mcp-lightcast:latest

# Or with environment file
docker run --rm -it --env-file .env ghcr.io/lawwu/mcp-lightcast:latest
```

## ⚙️ Configuration

### Environment Variables

Create a `.env` file with your Lightcast API credentials:

```bash
# Required - Lightcast API Configuration
LIGHTCAST_CLIENT_ID=your_client_id_here
LIGHTCAST_CLIENT_SECRET=your_client_secret_here

# Optional - API Configuration (with defaults)
LIGHTCAST_BASE_URL=https://api.lightcast.io
LIGHTCAST_OAUTH_URL=https://auth.emsicloud.com/connect/token
LIGHTCAST_OAUTH_SCOPE=emsi_open
LIGHTCAST_RATE_LIMIT=1000

# Optional - MCP Server Configuration
MCP_SERVER_NAME=lightcast-mcp-server
LOG_LEVEL=INFO
MASK_ERROR_DETAILS=true
```

### Lightcast API Access

To use this server, you need:

1. 📝 A [Lightcast API account](https://lightcast.io/open-skills/access)
2. 🔑 Client ID and Client Secret for OAuth2 authentication
3. 🎯 Access to the following Lightcast APIs:
   - Titles API - Job title search and normalization
   - Skills API - Skills search and categorization
   - Classification API - Occupation code mapping
   - Similarity API - Skills and occupation relationships

## 🎯 Usage

### Command Line Interface

The server includes a comprehensive CLI with multiple options:

```bash
# Basic usage (uses streamable-http on port 3000 by default)
mcp-lightcast

# Use stdio transport (for Claude Desktop integration)
mcp-lightcast --transport stdio

# Use streamable-http transport with custom port
mcp-lightcast --transport streamable-http --port 8080

# With custom log level
mcp-lightcast --log-level DEBUG

# Validate configuration without starting server
mcp-lightcast --validate-config

# Use custom environment file
mcp-lightcast --env-file /path/to/custom.env

# Quiet mode (no logging)
mcp-lightcast --quiet

# Show help
mcp-lightcast --help
```

### Development Commands

Using the included Makefile for easy development:

```bash
# Quick development setup and run
make dev

# Run with debug logging
make dev-server

# Run all quality checks
make check

# Run tests with coverage
make test-coverage

# Show Claude Desktop configuration
make claude-config
```

### Claude Desktop Integration

#### Using uv (Recommended)

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-lightcast",
        "mcp-lightcast"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

#### Using Docker

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "LIGHTCAST_CLIENT_ID",
        "-e", "LIGHTCAST_CLIENT_SECRET",
        "ghcr.io/lawwu/mcp-lightcast:latest"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

#### Using uvx (Isolated)

```json
{
  "mcpServers": {
    "lightcast": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-lightcast",
        "mcp-lightcast"
      ],
      "env": {
        "LIGHTCAST_CLIENT_ID": "your_client_id",
        "LIGHTCAST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### 🔧 Detailed Tool Usage Examples

#### **🎯 Skills Tools**

**search_skills** - Search skills with advanced filters
```python
skills = await search_skills(
    query="python programming",
    limit=10,
    skill_type="Hard Skill",  # Optional: filter by skill type
    category="Information Technology",  # Optional: filter by category
    version="latest"  # Uses latest API version
)
```

**extract_skills_from_text** - Extract skills from job descriptions
```python
# Extract skills with custom confidence threshold
skills = await extract_skills_from_text(
    text="Looking for Python developer with React and database experience...",
    confidence_threshold=0.7,
    version="latest"
)
```

**extract_skills_simple** - Extract skills with default settings
```python
# Quick skills extraction with default confidence (0.5)
skills = await extract_skills_simple(
    text="We need Java developers with Spring Boot experience",
    version="latest"
)
```

**bulk_retrieve_skills** - Efficient bulk skill retrieval
```python
# Get multiple skills in one request
skills = await bulk_retrieve_skills(
    skill_ids=["KS125LS6N7WP4S6SFTCK", "KS440C66FGP5WGWYMP0F"],
    version="latest"
)
```

#### **🏷️ Titles Tools**

**search_job_titles** - Search job titles
```python
titles = await search_job_titles(
    query="software engineer",
    limit=10,
    version="latest"
)
```

**get_job_title_details** - Get detailed title information
```python
title = await get_job_title_details(
    title_id="ET6850661D6AE5FA86",
    version="latest"
)
```

**bulk_retrieve_titles** - Efficient bulk title retrieval
```python
titles = await bulk_retrieve_titles(
    title_ids=["ET6850661D6AE5FA86", "ETBF8AE9187B3810C5"],
    version="latest"
)
```

#### **📊 Metadata Tools**

**get_skills_version_metadata** - API version information
```python
metadata = await get_skills_version_metadata(version="latest")
# Returns: version, skill_count, language_support, skill_types, etc.
```

**get_titles_version_metadata** - API version information  
```python
metadata = await get_titles_version_metadata(version="latest")
# Returns: version, title_count, removed_title_count, fields
```

#### **⚠️ Limited Availability Tools**
Some tools require premium authentication scopes or have endpoint limitations:

**normalize_job_title** - ❌ Requires premium scope
```python
# Currently returns 401 Unauthorized with emsi_open scope
result = await normalize_job_title("sr software dev")
```

**analyze_job_posting_skills** - ✅ Working via skills extraction
```python
# Uses skills extraction instead of normalization
result = await analyze_job_posting_skills(
    job_title="Software Engineer",
    job_description="Full job description text...",
    extract_from_description=True  # Uses working skills extraction
)
```

### 🎯 Example Workflows

#### **1. Extract Skills from Job Description**

```python
# Analyze a job posting to extract relevant skills
job_description = """
We're looking for a Senior Software Engineer with expertise in Python, 
React, and cloud technologies. Experience with Docker, Kubernetes, 
and AWS is required. Strong communication skills and team collaboration 
abilities are essential.
"""

# Extract skills with high confidence
skills = await extract_skills_from_text(
    text=job_description,
    confidence_threshold=0.8,
    version="latest"
)

print(f"High-confidence skills found: {len(skills)}")
for skill in skills:
    print(f"- {skill['name']} (confidence: {skill['confidence']:.2f})")
```

#### **2. Compare Skills Across Job Titles**

```python
# Search and compare skills requirements for different roles
titles = ["Data Scientist", "Machine Learning Engineer", "Software Engineer"]
title_skills = {}

for title in titles:
    # Search for the title
    title_results = await search_job_titles(query=title, limit=1)
    if title_results:
        title_id = title_results[0]['id']
        
        # Get detailed title information  
        title_details = await get_job_title_details(title_id)
        title_skills[title] = title_details
        
print("Job title comparison completed")
```

#### **3. Bulk Skills Analysis**

```python
# Efficiently analyze multiple skills at once
skill_names = ["Python", "JavaScript", "Machine Learning", "Docker"]

# First search for skil

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lawwu](https://github.com/lawwu)
- **Source:** [lawwu/mcp-lightcast](https://github.com/lawwu/mcp-lightcast)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lawwu-mcp-lightcast
- Seller: https://agentstack.voostack.com/s/lawwu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.