Scan to join WeChat groupREADME
🚀 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：手动部署
- 分叉此仓库。
- 将你的GitHub账户连接到Render。
- 在Render上创建一个新的Web服务。
- 连接你分叉的仓库。
- 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文件）
详细使用示例
请查看 使用指南，其中包含详细的使用示例和自然语言提示。
示例使用流程
- 加载数据：
Tool: load_h1b_data Parameters: {"year": 2024, "quarter": 4} - 搜索工作：
Tool: search_h1b_jobs Parameters: { "job_role": "Software Engineer", "state": "CA", "min_wage": 120000, "skip_agencies": true } - 获取公司详情：
Tool: get_company_stats Parameters: {"company_name": "Google"} - 导出结果：
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许可证。
贡献
欢迎提交问题和拉取请求，以改进本工具！