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. Built with FastMCP.

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

Note: Due to limitation of memory on the free instance, the server tends to go down. I'm happy to accept server donations for hosting.

✅ Real Data, Not Samples!

This server fetches actual H-1B application data directly from the U.S. Department of Labor's official disclosure files. Each dataset contains tens of thousands of real H-1B applications with:

• Real company names (Google, Microsoft, Amazon, etc.)
• Actual job titles and salaries
• Real work locations and contact information
• Certified application statuses

Data Source: https://www.dol.gov/agencies/eta/foreign-labor/performance

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

📖 How to Use

For detailed usage examples and natural language prompts, see the [Usage Guide](USAGE_GUIDE.md).

Quick Examples

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"

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

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)

3. get_company_stats

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

• Parameters:
• company_name: Company name to analyze

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

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"

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

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.

Example Usage Flow

1. Load the data:

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

1. Search for jobs:

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

1. Get company details:

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

1. Export results:

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

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

Current deployment: https://h1b-job-search-mcp.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