H1b Job Search MCP

🚀 H1B工作搜索MCP服务器

本项目是一个基于MCP（模型上下文协议）的服务器，借助美国劳工部的真实劳工条件申请（LCA）披露数据，实现H-1B工作搜索自动化。它基于 FastMCP 构建。

🚀 在线服务器：https://h1b-job-search-mcp.onrender.com/mcp

✨ 主要特性

• 📊 下载LCA数据：自动从劳工部下载并缓存H-1B LCA披露数据。
• 🔍 智能搜索：可按职位、地点和薪资筛选提供H-1B赞助的公司。
• 🏢 公司分析：获取特定公司的详细赞助统计信息。
• 📈 顶级赞助商：按赞助数量列出顶级H-1B赞助公司。
• 🚫 中介过滤：自动过滤掉人力资源中介机构，以找到直接雇主。
• 📁 导出结果：将筛选结果导出为CSV文件，便于进一步联系。
• 💾 数据缓存：智能缓存机制，避免重复下载大型数据集。
• 🤖 多LLM支持：支持Claude、ChatGPT、Gemini、Cursor和Poke等多种大语言模型。

📦 安装指南

本地开发设置

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

使用MCP检查器进行测试

# 终端1：启动服务器
python src/server.py

# 终端2：运行检查器
npx @modelcontextprotocol/inspector

打开 http://localhost:3000 ，使用“可流式传输的HTTP”传输方式连接到 http://localhost:8000/mcp。

部署

选项1：部署到Render

点击上方的“Deploy to Render”按钮。

选项2：手动部署

1. 分叉此仓库。
2. 将你的GitHub账户连接到Render。
3. 在Render上创建一个新的Web服务。
4. 连接你分叉的仓库。
5. Render将自动检测 render.yaml 配置。

你的服务器将在 https://your-service-name.onrender.com/mcp 上可用。当前部署地址为：https://h1b-job-search-mcp.onrender.com/mcp

💻 使用示例

快速示例

你可以自然地与系统交流，ask 工具能够理解简单的英语指令：

• "Load the latest H-1B data"（加载最新的H-1B数据）
• "Find software engineer jobs in California paying over 150k"（查找加利福尼亚州薪资超过15万美元的软件工程师职位）
• "Tell me about Google's H-1B sponsorships"（告诉我有关谷歌的H-1B赞助情况）
• "Export data scientist positions to CSV"（将数据科学家职位导出为CSV文件）

详细使用示例

请查看 使用指南，其中包含详细的使用示例和自然语言提示。

示例使用流程

1. 加载数据：

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

2. 搜索工作：

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

3. 获取公司详情：

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

4. 导出结果：

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

📚 详细文档

可用的MCP工具

1. load_h1b_data

从劳工部下载并加载H-1B LCA数据。

• 参数：
  • year：财政年度（默认：2024）
  • quarter：季度（1 - 4，默认：4）
  • force_download：即使有缓存也强制重新下载

2. search_h1b_jobs

按职位和地点搜索提供H-1B赞助的公司。

• 参数：
  • job_role：要搜索的职位名称（例如："Software Engineer"）
  • city：工作城市（可选）
  • state：工作州代码（可选，例如："CA"）
  • min_wage：最低薪资筛选条件（可选）
  • max_results：返回的最大结果数
  • skip_agencies：跳过人力资源中介机构（默认：true）

3. get_company_stats

获取特定公司的详细H-1B赞助统计信息。

• 参数：
  • company_name：要分析的公司名称

4. get_top_sponsors

按申请数量列出顶级H-1B赞助公司。

• 参数：
  • limit：返回的公司数量
  • exclude_agencies：排除人力资源中介机构

5. export_results

将筛选后的H-1B结果导出为CSV文件。

• 参数：
  • job_role：要筛选的职位名称
  • city：城市筛选条件（可选）
  • state：州筛选条件（可选）
  • filename：输出文件名
  • max_results：要导出的最大结果数

6. get_available_data

检查可用的LCA数据周期和缓存文件。

7. ask（自然语言接口）🎯

你可以用简单的英语与H-1B搜索系统交流！

• 用法：用自然语言描述你的需求
• 示例：
  • "I'm a software engineer looking for jobs in the Bay Area"（我是一名软件工程师，正在湾区寻找工作）
  • "Show me data scientist positions paying over 180k"（给我展示薪资超过18万美元的数据科学家职位）
  • "Which companies sponsor the most H-1B visas?"（哪些公司赞助的H-1B签证最多？）
  • "Tell me about Microsoft's H-1B program"（告诉我有关微软的H-1B计划）

多LLM支持

本MCP服务器支持多个大语言模型平台。详细的集成说明请参考 docs/LLM_INTEGRATION.md。

快速设置（按平台）

Claude桌面版

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

ChatGPT/OpenAI

使用 PORT=8000 python src/server.py 启动服务器，并使用 config/openai_config.json 中的OpenAPI模式。

Google Gemini

使用 config/gemini_config.json 中的函数声明进行配置。

Cursor IDE

将 config/cursor_config.json 放置在 .cursor/mcp-config.json 中并重新加载。

Interaction Poke

在Poke设置中使用 config/poke_config.json。

完整的设置指南、测试程序和故障排除请参考 docs/LLM_INTEGRATION.md。

🔧 技术细节

数据来源

本工具使用美国劳工部外国劳工认证数据中心公开的LCA披露数据，包括：

• 雇主信息
• 职位名称和薪资
• 工作地点
• 案件状态
• 联系信息（如有）

注意：此数据显示了历史H-1B赞助模式，与雇主联系时请始终直接核实当前的赞助政策。

隐私与法律

• 所有使用的数据均来自美国劳工部的公开信息。
• 不访问任何私人或机密信息。
• 与雇主联系时，请负责任且专业地使用本工具。
• 尊重公司的沟通偏好。

定制化

你可以通过修改 src/server.py 来添加自定义过滤逻辑或额外的工具：

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

故障排除

• 数据加载失败：检查你的网络连接，并确认年份/季度数据存在。
• 未找到结果：尝试使用更宽泛的搜索词或检查不同的季度。
• 内存问题：完整数据集可能很大，考虑在pandas中使用 nrows 参数。
• 缓存问题：删除 data_cache 目录以强制重新下载数据。

📄 许可证

本项目采用MIT许可证。

贡献

欢迎提交问题和拉取请求，以改进本工具！