job search MCP server

JobSpy MCP服务器

一个自给自足的 MCP（模型上下文协议） 服务器 它将多站点作业抓取作为AI可调用工具公开。 将其连接到任何兼容MCP的客户端（Claude Desktop、Cursor、自定义代理）并搜索 LinkedIn、Indeed、Glassdoor、ZipRecruiter、Google Jobs、， 以及区域委员会——所有这些都是通过自然语言或结构化工具调用实现的。

scraper实现直接在该存储库中提供；无外部 python-jobspy 包裹是必需的。

______________________________________________________________________

特性

• 4个MCP工具 — scrape_jobs_tool, get_supported_countries, get_supported_sites, get_job_search_tips
• 13个招聘板 --LinkedIn、Indeed、Glassdoor、ZipRecruiter、谷歌招聘、Bayt（中东）、Naukri（印度）、Stepstone（德国/DACH）、Xing（德国）、柏林创业公司招聘、欢迎来到丛林、欧盟创业公司、join.com
• 标准化输出模式 — id, company_name, role_title, description, description_source, job_type, job_url, location, work_mode, language, source_platform, scraped_at, content_hash
• 模式稳定的JSON输出 --所有公共工具风格的API都返回JSON信封，以实现一致的客户端解析
• 高级过滤 --工作类型、仅远程、发布年龄、特定城市、易于申请、分页偏移
• 进度报告 --通过MCP上下文实时更新进度
• Docker支持 --单映像部署
• 完全自给自足 --刮板源由以下供应商提供 jobspy_mcp_server/jobspy_scrapers/

API 参考

规范的API契约存在于 docs/API_集成.md.

将该文档用于：

• MCP工具参数和JSON响应形状
• CLI调用和stdout合约
• MCP传输端点详细信息
• 基于markdown的旧助手输出的迁移指南

______________________________________________________________________

技术栈

______________________________________________________________________

项目结构

jobspy-mcp-server/
├── jobspy_mcp_server/
│   ├── __init__.py            # Package exports
│   ├── __main__.py            # python -m entrypoint
│   ├── cli.py                 # JSON-only standalone CLI entrypoint
│   ├── json_output.py         # Shared normalized job serialization
│   ├── server.py              # MCP tool definitions (scrape_jobs_tool, etc.)
│   └── jobspy_scrapers/       # Vendored scraper implementation
│       ├── __init__.py        # scrape_jobs() public API
│       ├── model.py           # JobPost, Country, and other data models
│       ├── util.py            # Shared utilities
│       ├── exception.py       # Custom exceptions
│       ├── linkedin/          # LinkedIn scraper
│       ├── indeed/            # Indeed scraper
│       ├── glassdoor/         # Glassdoor scraper
│       ├── google/            # Google Jobs scraper
│       ├── ziprecruiter/      # ZipRecruiter scraper
│       ├── bayt/              # Bayt (Middle East) scraper
│       ├── naukri/            # Naukri (India) scraper
│       ├── stepstone/         # Stepstone (Germany/DACH) scraper
│       ├── xing/              # Xing (Germany) scraper
│       ├── berlinstartupjobs/ # Berlin Startup Jobs scraper
│       ├── welcometothejungle/# Welcome to the Jungle scraper (Algolia API)
│       ├── eustartups/        # EU-Startups jobs board scraper
│       └── join/              # join.com scraper
├── test/
│   ├── test_jobspy_mcp.py     # Unit tests (mocked)
│   └── test_server.py         # MCP protocol smoke test
├── Dockerfile
├── pyproject.toml
├── requirements.lock          # Pinned dependency lockfile
├── THIRD_PARTY_LICENSES.md
└── LICENSE

______________________________________________________________________

安装

先决条件

• Python 3.10或更高版本
• uv （推荐） 或 pip

紫外线（推荐）

git clone https://github.com/yourorg/jobspy-mcp-server
cd jobspy-mcp-server
uv sync

使用pip

git clone https://github.com/yourorg/jobspy-mcp-server
cd jobspy-mcp-server
pip install -e .

______________________________________________________________________

运行服务器

紫外线：

uv run python -m jobspy_mcp_server

python

python -m jobspy_mcp_server

已安装的脚本入口点：

jobspy-mcp-server

Docker：

docker build -t jobspy-mcp-server .
docker run --rm -it jobspy-mcp-server

服务器通过以下方式进行通信 标准 并且被设计为由不通过HTTP访问的MCP客户端启动。

MCP检查器（交互式调试UI）

要在本地测试服务器而不配置客户端，请使用 MCP检查员:

npx @modelcontextprotocol/inspector python -m jobspy_mcp_server

然后打开 http://localhost:6274 在您的浏览器中。

一步一步：打电话 scrape_jobs_tool 来自检查员

1. 启动检查器 --运行上面的命令。终端显示 MCP Inspector is up and running at http://localhost:6274.
2. 打开用户界面 首选 http://localhost:6274 在您的浏览器中。
3. 连接 --点击 连接 顶部栏中的按钮。服务器连接后，状态指示灯变为绿色。
4. 浏览工具 --点击 工具 左侧边栏中的选项卡。你会看到 scrape_jobs_tool, get_supported_countries, get_supported_sites，以及 get_job_search_tips.
5. 选择 scrape_jobs_tool --点击它。右侧面板显示了一个包含所有参数的输入表单。
6. 填写参数 --在表单字段中输入值：

- search_term （必填）：例如。 software engineer - cities：例如。 ["Munich", "Berlin", "Frankfurt"] （可选；指定城市以限制搜索） - country_indeed：例如。 germany （默认值：美国） - site_name：例如。 ["indeed"] - results_wanted：例如。 5 - 将其他字段保留为默认值或根据需要进行调整。

1. 运行该工具 --单击 运行工具 按钮。
2. 查看结果 --响应以JSON信封的形式出现在下面的面板中 ok, jobs，以及 error.

示例：检查器中的JSON输出

在检查器窗体中设置这些参数：

重要提示： 默认情况下，LinkedIn列表不包括职位描述。 集 linkedin_fetch_description 到 true 获取每个作业的完整描述。 这使得每个作业多出一个HTTP请求，因此速度较慢。 如果你设置它 false，the description 字段将是 null 为了 LinkedIn结果。这不会影响其他网站，如Indeed或Glassdoor， 其中自动包括描述。

响应将是一个JSON信封，如下所示：

{
  "ok": true,
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "company_name": "Acme Corp",
      "role_title": "Android Engineer",
      "description": "...",
      "description_source": "detail_page",
      "job_type": "fulltime",
      "job_url": "https://www.linkedin.com/jobs/view/1234567890",
      "location": "San Francisco, CA",
      "work_mode": "hybrid",
      "language": "English",
      "source_platform": "linkedin",
      "scraped_at": "2026-04-03T09:00:00.000000+00:00",
      "content_hash": "3af6df4f2570a7e2d23c76fc6e43d65ff15ec1881a627f2f6fb652f9d4a686f5"
    }
  ],
  "error": null
}

检查员故障排除

• “连接”按钮保持灰色 --确保服务器进程在终端中启动时没有错误。检查一下 python -m jobspy_mcp_server 它自己跑得很干净。
• 工具返回空结果 --试试看 indeed 作为网站（最可靠），使用广泛 search_term，并减少 results_wanted 到 3.
• site_name 格式 --在检查器窗体中，将其作为JSON数组输入： ["indeed"] 或 ["indeed", "linkedin"]。不要使用纯逗号分隔的字符串。
• 端口冲突 --如果端口6274正在使用中，检查器将在终端中打印备用URL。

______________________________________________________________________

MCP客户端配置

克劳德桌面版

Windows配置路径： %APPDATA%\Claude\claude_desktop_config.json\ macOS配置路径： ~/Library/Application Support/Claude/claude_desktop_config.json

使用紫外线（推荐）：

{
  "mcpServers": {
    "jobspy": {
      "command": "uv",
      "args": ["run", "python", "-m", "jobspy_mcp_server"],
      "cwd": "/absolute/path/to/jobspy-mcp-server"
    }
  }
}

使用已安装的脚本：

{
  "mcpServers": {
    "jobspy": {
      "command": "jobspy-mcp-server"
    }
  }
}

使用Docker：

{
  "mcpServers": {
    "jobspy": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "jobspy-mcp-server"]
    }
  }
}

编辑配置后，重新启动Claude Desktop。

开爪

OpenClaw没有原生MCP客户端支持，因此集成使用了两个桥接器：

快速入门-CLI（exec）：

# Install the package (once)
pip install -e /path/to/jobspy-mcp-server

# Test the CLI (JSON output)
jobspy-search "python developer" --cities "Munich,Berlin,Frankfurt" --country "Germany" --sites "linkedin" --results 5

# Pipeline smoke test (OpenClaw/developer integration)
jobspy-search "software engineer" --cities "Berlin" --sites "stepstone,xing" --job-type "contract" --results 1

快速入门--HTTP（web_fetch）：

# Start the server with SSE transport
jobspy-mcp-server --transport sse --host 127.0.0.1 --port 8765

# SSE endpoint: GET  http://127.0.0.1:8765/sse
# Messages:     POST http://127.0.0.1:8765/messages

OpenClaw技能包含在 assets/openclaw-skill/SKILL.md.\ 将其复制到您的OpenClaw工作区：

# Windows
copy assets\openclaw-skill\SKILL.md %USERPROFILE%\.openclaw\workspace\skills\jobspy-search\SKILL.md

# macOS / Linux
cp assets/openclaw-skill/SKILL.md ~/.openclaw/workspace/skills/jobspy-search/SKILL.md

有关完整的集成指南——端点、JSON-RPC示例、故障排除——请参阅 docs/openclaw-integration.md.

______________________________________________________________________

如何寻找工作

一旦服务器连接到客户端，您就可以通过自然语言提示或直接调用该工具来搜索作业。

自然语言（克劳德桌面）

键入聊天内容：

Search for Python developer jobs in New York on LinkedIn

Find remote data scientist roles on Indeed posted in the last 48 hours

Look for full-time software engineer jobs in London using LinkedIn and Glassdoor, fetch full descriptions

Find senior Java developer contract jobs on LinkedIn and Indeed, return 15 results

客户端会自动将这些转换为 scrape_jobs_tool 电话。

直接工具调用

仅限LinkedIn：

{
  "search_term": "software engineer",
  "location": "San Francisco, CA",
  "site_name": ["linkedin"],
  "results_wanted": 10,
  "linkedin_fetch_description": true
}

LinkedIn+Indeed合并：

{
  "search_term": "data scientist",
  "location": "New York, NY",
  "site_name": ["linkedin", "indeed"],
  "results_wanted": 15,
  "hours_old": 72
}

所有主要板上的远程作业：

{
  "search_term": "frontend developer",
  "is_remote": true,
  "site_name": ["linkedin", "indeed", "glassdoor"],
  "job_type": "fulltime",
  "results_wanted": 15
}

印度/Naukri地区搜索：

{
  "search_term": "machine learning engineer",
  "location": "Bangalore",
  "site_name": ["naukri", "linkedin"],
  "results_wanted": 15
}

中东/海湾搜索：

{
  "search_term": "project manager",
  "location": "Dubai",
  "site_name": ["bayt", "indeed"],
  "country_indeed": "united arab emirates",
  "results_wanted": 15
}

结构化JSON输出（默认）：

{
  "search_term": "android engineer",
  "location": "San Francisco, CA",
  "site_name": ["linkedin"],
  "results_wanted": 5
}

返回一个具有稳定顶级键的JSON信封： ok, jobs，以及 error.

• 成功： ok=true, jobs=[...], error=null
• 空结果： ok=true, jobs=[], error=null
• 验证/运行时失败： ok=false, jobs=[], error={"code":"...","message":"..."}

每个作业对象仅包含： id （UUID）， company_name, role_title, description, description_source, job_type, job_url, location, work_mode, language, source_platform, scraped_at，以及 content_hash 哪里 content_hash = SHA256(title + company + location) 正常化后。

______________________________________________________________________

MCP工具参考

scrape_jobs_tool

在多个工作板上搜索工作。

参数注释：

• site_name 根据服务器中的固定允许列表进行验证。任何无效值都会返回错误。
• site_name 每个请求最多支持5个值。
• results_wanted 是全市范围内每个站点的请求上限。例子： results_wanted=1 每个选定站点最多可提取一个作业。
• country_indeed 接受以下别名 usa, us, united states.使用 get_supported_countries 查看完整列表。
• linkedin_fetch_description=true 增加了运行时间，因为它触发了额外的页面/API获取。

get_supported_countries

返回接受的国家标识符的完整列表 country_indeed.

What countries are supported for job searches?

get_supported_sites

返回所有支持的工作板名称以及说明和使用指南。

What job boards can I search?

get_job_search_tips

返回一份深入的指南，涵盖搜索词优化、网站选择、性能提示和常见故障排除。

Give me tips for finding jobs faster

______________________________________________________________________

支持的工作板

提供者参数支持矩阵

传说： Yes =直接支持， Partial =支持警告/特定于提供商的行为， No =忽略或未实现。

提供商警告和限制

• LinkedIn：比其他来源更严格的反机器人行为和退避敏感性。
• 事实上：国家选择是有意义的，应该为非美国搜索设置。
• Glassdoor：内部要求将结果限制在900。
• 谷歌工作：内部将搜索结果限制在900个以内，具体取决于光标的可用性。
• ZipRecruiter：最适合美国/加拿大；全球行为是有限的。
• Bayt，Naukri：高级过滤器保证较少的区域供应商。
• Stepstone，Xing：基于HTML抓取的德国/DACH区域提供商。

______________________________________________________________________

如何添加新提供者

此项目在以下情况下使用每个模块的提供程序架构 jobspy_mcp_server/jobspy_scrapers/.

1.创建提供者模块

创建新文件夹：

jobspy_mcp_server/jobspy_scrapers//

推荐文件：

• __init__.py （必填）：刮刀类实现。
• constant.py （可选但推荐）：URL、有效载荷模板、选择器、标头。
• util.py （可选）：特定于提供程序的解析帮助程序。

实现一个继承抽象的类 Scraper 并返回 JobResponse 从 scrape(scraper_input: ScraperInput).

2.注册提供者枚举

更新 Site 在 jobspy_mcp_server/jobspy_scrapers/model.py 使用新的字符串值 site_name.

例子：

class Site(Enum):
  # ... existing providers
  MY_PROVIDER = "my_provider"

3.添加刮刀映射

更新 jobspy_mcp_server/jobspy_scrapers/__init__.py:

• 为新的scraper类添加导入。
• 在中添加映射 SCRAPER_MAPPING.

例子：

from jobspy_mcp_server.jobspy_scrapers.my_provider import MyProvider

SCRAPER_MAPPING = {
  # ... existing mappings
  Site.MY_PROVIDER: MyProvider,
}

4.暴露MCP层中的提供者

更新中的验证允许列表 jobspy_mcp_server/guardrails.py:

• 将您的提供商添加到 VALID_SITES.
• 在中添加描述 get_supported_sites 输出。
• 在README中添加一个直接使用示例（推荐）。

5.遵循数据合同预期

填充 JobPost 一贯地：

• 必填质量字段： title, job_url, company_name, location 如果可用。
• 可选富集： description、补偿字段， date_posted, job_type, is_remote.
• 在需要的地方使用现有的转换器（markdown/plain）规范文本输出。

6.处理错误和恢复能力

• 捕获特定于提供者的请求/解析失败并返回 JobResponse(jobs=[]) 而不是破坏整个运行。
• 通过现有的提供程序记录器使用 create_logger 公用事业。
• 为反机器人或限速提供商添加受控延迟/回退。

7.安全检查表（必填）

• 在返回之前，验证并规范任何抓取的URL。
• 除非故意要求，否则避免返回不安全的原始HTML。
• 对于描述，更喜欢标记/纯转换。
• 请勿对提供程序模块中的机密、API密钥或凭据进行硬编码。

8.测试检查表

在中添加或扩展测试 test/:

• test_jobspy_mcp.py：验证新站点名称传递 scrape_jobs_tool 验证并显示在支持的站点输出中。
• 提供者单元测试：解析器健壮性、空结果处理、分页行为和偏移/结果切片。
• test_server.py：确保MCP服务器结构/工具保持完好。

9.常见的集成错误

• 添加了枚举但忘记了 SCRAPER_MAPPING 导入/输入。
• 添加了刮刀映射，但忘记了 guardrails.py VALID_SITES 允许列表。
• 返回原始结构，而不是 JobResponse/JobPost 模式。
• 忽略偏移/结果切片，并生成无界结果集。
• 添加了提供程序，但忘记了README支持的网站文档。

______________________________________________________________________

配置

基本操作不需要环境变量。可选运行时行为：

______________________________________________________________________

测试

# Run all unit tests (no network required)
uv run pytest test -v

# Exclude integration tests (default CI mode)
uv run pytest test -q -m "not integration"

# Run integration tests (live network, real job boards)
uv run pytest test -v -m integration

# Run a specific file
uv run pytest test/test_jobspy_mcp.py -v
uv run pytest test/test_server.py -v

随着 pip 而不是 uv:

pytest test -v

______________________________________________________________________

构建和部署

本地可编辑安装

uv sync
# or
pip install -e .

码头工人

# Build
docker build -t jobspy-mcp-server .

# Run (stdio mode — attach via MCP client)
docker run --rm -it jobspy-mcp-server

软件包构建（wheel/slist）

uv build
# outputs dist/jobspy_mcp_server-1.0.0-*.whl

______________________________________________________________________

故障排除

模块或导入错误

uv sync            # reinstall all deps
python -m jobspy_mcp_server   # confirm the entry point starts cleanly

未返回任何结果

• 拓宽 search_term （字数更少）
• 尝试 indeed 首先作为一个单一的网站
• 检查城市拼写 cities；用于非美国搜索集 country_indeed 明确地

速率限制/HTTP 429

• 减少 results_wanted （从10开始）
• 避免在LinkedIn上搜索大量内容
• 在连续搜索之间添加间距
• 使用 proxies 用于重复的自动搜索

Claude Desktop未检测到工具

• 验证 claude_desktop_config.json 是有效的JSON
• 确认 cwd 指向存储库根目录
• 配置更改后重新启动Claude Desktop
• 手动运行服务器一次，确认没有启动错误

linkedin_fetch_description 非常慢

• 仅在需要完整描述时启用此功能；它为每个作业发出一个额外的HTTP请求

______________________________________________________________________

贡献

1. 分叉存储库并创建功能分支。
2. 在适用的情况下，通过测试进行更改。
3. 确保所有单元测试通过： uv run pytest test -q -m "not integration"
4. 打开一个包含更改清晰描述的拉取请求。

代码样式由强制执行 black （线长88）。提交前运行：

uv run black .

______________________________________________________________________

归因

刮刀的实施(jobspy_mcp_server/jobspy_scrapers/)来源于 JobSpy 由Cullen Watson（麻省理工学院许可证）提供 进入此存储库进行单个项目部署。

完整的许可证文本位于 第三阶段_许可.md.

______________________________________________________________________

许可证

MIT许可证——见 许可证 了解详情。