H1B Job Search MCP Server

How to use

You interact with the H-1B Job Search MCP Server using an MCP client. Start by loading the latest H-1B data, then perform targeted searches for job roles in your preferred locations, and finally export or view analytics for companies and sponsors. You can phrase your requests in plain language and let the client translate them into MCP tool calls.

Typical workflows you can perform include loading the data for a specific year and quarter, searching for roles by title and location, retrieving detailed sponsorship stats for a company, listing the top sponsors by volume, and exporting filtered results to CSV for outreach.

If you prefer a quick start, you can ask the system to load data, run a job search for a given role in a state, or export results for a chosen job title and location. The built-in natural language interface accepts straightforward prompts like “Load the latest H-1B data” or “Show me software engineer jobs in California paying over 150k.”

How to install

Prerequisites: you need Python installed on your machine. You will also set up a environment to run the MCP server locally.

Step 1: Clone the project repository to your local machine.

Step 2: Create and activate a Python environment.

Step 3: Install the required Python packages.

Step 4: Run the MCP server. Use the command shown in the code blocks below to start the server and connect with an MCP client.

Configuration and usage examples

The server exposes a live HTTP endpoint you can connect to with an MCP client. You can also run the server locally in stdio mode to test with an inspector and connect the client to your local MCP stream.

{
  "mcpServers": [
    {
      "type": "http",
      "name": "h1b_job_search",
      "url": "https://h1b-job-search-mcp.onrender.com/mcp",
      "args": []
    },
    {
      "type": "stdio",
      "name": "h1b_job_search",
      "command": "python",
      "args": ["src/server.py"]
    }
  ]
}

Data source and privacy

The server uses public H-1B LCA disclosure data from the U.S. Department of Labor. It includes employer names, job titles, wages, work locations, case statuses, and contact information when available. Use this data responsibly and verify current sponsorship policies directly with employers.

Deployment and live server

You can run a live MCP server instance or deploy to a hosting service. The live endpoint is available at the provided URL, which hosts the server and makes the MCP interface accessible to clients.

Troubleshooting

If data loading fails, ensure you have network access and that the requested year/quarter data exists. If searches return no results, broaden your terms or try a different quarter. Large datasets may require caching considerations to avoid repeated downloads.

Notes

This server supports multiple MCP tools for data loading, searching, statistics, top sponsors, and exporting results, all designed to help you analyze H-1B sponsorship patterns.

load_h1b_data

Downloads and loads H-1B LCA data from the Department of Labor for the specified year and quarter, caching data to avoid repeated downloads.

search_h1b_jobs

Filters H-1B sponsoring companies by job role, location, and wage thresholds to return matching results.

get_company_stats

Provides detailed sponsorship statistics for a specific company.

get_top_sponsors

Lists top H-1B sponsoring companies by application volume with optional filtering for agencies.

export_results

Exports filtered H-1B results to a CSV file for outreach and analysis.

get_available_data

Checks available LCA data periods and cached files.

ask

Natural language interface to describe your data needs in plain English.