H1b Job Search MCP

🚀 H1B Job Search MCP Server

An MCP (Model Context Protocol) server that automates H-1B job searching using REAL U.S. Department of Labor LCA disclosure data.

🚀 Live Server: https://h1b-job-search-mcp.onrender.com/mcp

🚀 Quick Start

This MCP server is designed to automate H-1B job searching using real U.S. Department of Labor LCA disclosure data. It's built with FastMCP.

✨ Features

• 📊 Download LCA Data: Automatically downloads and caches H-1B LCA disclosure data from the Department of Labor.
• 🔍 Smart Search: Filter H-1B sponsoring companies by job role, location, and wage.
• 🏢 Company Analytics: Get detailed sponsorship statistics for specific companies.
• 📈 Top Sponsors: List top H-1B sponsoring companies by volume.
• 🚫 Agency Filtering: Automatically filter out staffing agencies to find direct employers.
• 📁 Export Results: Export filtered results to CSV for easy outreach.
• 💾 Data Caching: Intelligent caching to avoid re-downloading large datasets.
• 🤖 Multi-LLM Support: Works with Claude, ChatGPT, Gemini, Cursor, and Poke.

📦 Installation

Local Development Setup

git clone <your-repo-url>
cd mcp-server-template
conda create -n h1b-mcp python=3.13
conda activate h1b-mcp
pip install -r requirements.txt

💻 Usage Examples

Basic Usage

For detailed usage examples and natural language prompts, see the Usage Guide.

Just talk naturally! The ask tool understands plain English:

• "Load the latest H-1B data"
• "Find software engineer jobs in California paying over 150k"
• "Tell me about Google's H-1B sponsorships"
• "Export data scientist positions to CSV"

Advanced Usage

Here are some examples of using the available MCP tools:

1. load_h1b_data

Download and load H-1B LCA data from the Department of Labor.

• Parameters:
  • year: Fiscal year (default: 2024)
  • quarter: Quarter 1 - 4 (default: 4)
  • force_download: Force re-download even if cached

Tool: load_h1b_data
Parameters: {"year": 2024, "quarter": 4}

2. search_h1b_jobs

Search for H-1B sponsoring companies by job role and location.

• Parameters:
  • job_role: Job title to search (e.g., "Software Engineer")
  • city: Work city (optional)
  • state: Work state code (optional, e.g., "CA")
  • min_wage: Minimum wage filter (optional)
  • max_results: Maximum results to return
  • skip_agencies: Skip staffing agencies (default: true)

Tool: search_h1b_jobs
Parameters: {
  "job_role": "Software Engineer",
  "state": "CA",
  "min_wage": 120000,
  "skip_agencies": true
}

3. get_company_stats

Get detailed H-1B sponsorship statistics for a specific company.

• Parameters:
  • company_name: Company name to analyze

Tool: get_company_stats
Parameters: {"company_name": "Google"}

4. get_top_sponsors

List top H-1B sponsoring companies by application volume.

• Parameters:
  • limit: Number of companies to return
  • exclude_agencies: Exclude staffing agencies

5. export_results

Export filtered H-1B results to a CSV file.

• Parameters:
  • job_role: Job title to filter
  • city: City filter (optional)
  • state: State filter (optional)
  • filename: Output filename
  • max_results: Maximum results to export

Tool: export_results
Parameters: {
  "job_role": "Data Scientist",
  "state": "NY",
  "filename": "ny_data_scientists.csv"
}

6. get_available_data

Check available LCA data periods and cached files.

7. ask (Natural Language Interface) 🎯

Talk to the H-1B search in simple English!

• Usage: Just describe what you want in plain language
• Examples:
  • "I'm a software engineer looking for jobs in the Bay Area"
  • "Show me data scientist positions paying over 180k"
  • "Which companies sponsor the most H-1B visas?"
  • "Tell me about Microsoft's H-1B program"

📚 Documentation

Local Development

Test with MCP Inspector

# Terminal 1: Start the server
python src/server.py

# Terminal 2: Run the inspector
npx @modelcontextprotocol/inspector

Open http://localhost:3000 and connect to http://localhost:8000/mcp using "Streamable HTTP" transport.

Deployment

Option 1: Deploy to Render

Click the "Deploy to Render" button above.

Option 2: Manual Deployment

1. Fork this repository
2. Connect your GitHub account to Render
3. Create a new Web Service on Render
4. Connect your forked repository
5. Render will automatically detect the render.yaml configuration

Your server will be available at https://your-service-name.onrender.com/mcp

Multi-LLM Support

This MCP server works with multiple LLM platforms. For detailed integration instructions, see docs/LLM_INTEGRATION.md.

Quick Setup by Platform

Claude Desktop

{
  "mcpServers": {
    "h1b-search": {
      "command": "python",
      "args": ["/path/to/src/server.py"]
    }
  }
}

ChatGPT/OpenAI

Run server with PORT=8000 python src/server.py and use the OpenAPI schema in config/openai_config.json.

Google Gemini

Configure with function declarations using config/gemini_config.json.

Cursor IDE

Place config/cursor_config.json in .cursor/mcp-config.json and reload.

Interaction Poke

Use config/poke_config.json in Poke settings.

See docs/LLM_INTEGRATION.md for complete setup guides, testing procedures, and troubleshooting.

Data Source

This tool uses publicly available LCA disclosure data from the U.S. Department of Labor's Foreign Labor Certification Data Center. The data includes:

• Employer information
• Job titles and wages
• Work locations
• Case status
• Contact information (when available)

Note: This data shows historical H-1B sponsorship patterns. Always verify current sponsorship policies with employers directly.

Privacy & Legal

• All data used is publicly available from the U.S. Department of Labor
• No private or confidential information is accessed
• Use responsibly and professionally when contacting employers
• Respect company communication preferences

Customization

Add custom filtering logic or additional tools by modifying src/server.py:

@mcp.tool
def custom_analysis(parameter: str) -> dict:
    """Your custom H-1B data analysis."""
    # Your implementation here
    pass

Troubleshooting

• Data not loading: Check your internet connection and verify the year/quarter exists
• No results found: Try broader search terms or check different quarters
• Memory issues: The full dataset can be large; consider using nrows parameter in pandas
• Cache issues: Delete the data_cache directory to force fresh downloads

Contributing

Feel free to submit issues and pull requests to improve this tool!

📄 License

MIT