Adzuna Job Search MCP

Adzuna Jobs MCP 服务

一个模型上下文协议（MCP）服务，可让 AI 助手访问 Adzuna Job Search API。搜索职位、分析薪资数据，并调查 12 个国家的雇主。

功能

• 职位搜索 - 搜索数百万条职位信息，可按地点、薪资、职位类型等条件筛选
• 薪资分析 - 获取薪资直方图、地区对比和历史趋势
• 公司调查 - 按招聘数量查找顶尖雇主
• 多国家支持 - 使用当地货币访问 12 个国家的就业市场

支持的国家/地区

代码	国家/地区	货币
gb	英国	GBP £
us	美国	USD $
de	德国	EUR €
fr	法国	EUR €
au	澳大利亚	AUD $
nz	新西兰	NZD $
ca	加拿大	CAD $
in	印度	INR ₹
pl	波兰	PLN zł
br	巴西	BRL R$
at	奥地利	EUR €
za	南非	ZAR R

可用工具

工具	描述
search_jobs	使用筛选条件（关键词、地点、薪资、职位类型）搜索职位
get_categories	获取某个国家/地区的有效职位类别标签
get_salary_histogram	获取职位搜索的薪资分布数据
get_top_companies	按空缺职位数量获取顶尖雇主
get_geodata	获取按地理区域细分的薪资数据
get_salary_history	获取薪资随时间变化的历史趋势
get_api_version	获取当前 Adzuna API 版本

前提条件

• Python 3.10+
• Adzuna API 凭据（免费）

获取 Adzuna API 凭据

1. 前往 Adzuna Developer Portal
2. 注册免费账户
3. 创建新应用
4. 复制你的 App ID 和 App Key

安装

选项 1：从 PyPI 安装（推荐）

pip install adzuna-mcp

也可以使用 uvx 独立运行：

uvx adzuna-mcp

选项 2：从源代码安装

git clone https://github.com/folarinakinloye/adzuna-mcp.git
cd adzuna-mcp
pip install -e .

选项 3：开发环境设置

git clone https://github.com/folarinakinloye/adzuna-mcp.git
cd adzuna-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

配置环境变量

创建包含 Adzuna 凭据的 .env 文件：

ADZUNA_APP_ID=your_app_id_here
ADZUNA_APP_KEY=your_app_key_here

使用

使用 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adzuna-jobs": {
      "command": "/path/to/adzuna-mcp/venv/bin/python",
      "args": ["/path/to/adzuna-mcp/server.py"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。

使用 Cursor

将以下内容添加到 Cursor MCP 设置中（项目内的 .cursor/mcp.json 或全局配置）：

{
  "mcpServers": {
    "adzuna-jobs": {
      "command": "/path/to/adzuna-mcp/venv/bin/python",
      "args": ["/path/to/adzuna-mcp/server.py"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}

使用其他 MCP 客户端

直接运行该服务：

# Activate virtual environment
source venv/bin/activate

# Run with stdio transport (default)
python server.py

# Or use FastMCP CLI
fastmcp run server.py:mcp

开发模式

FastMCP 提供带交互式检查器的开发模式：

fastmcp dev server.py

这会打开基于浏览器的界面，用于测试工具。

示例提示词

连接后，你可以询问 AI 助手：

求职搜索：

• "查找伦敦年薪超过 £60,000 的软件工程师职位"
• "搜索美国的远程 Python 开发人员职位"
• "显示德国的数据科学职位"

薪资调查：

• "英国机器学习工程师的典型薪资是多少？"
• "比较伦敦和曼彻斯特的软件工程师薪资"
• "过去一年数据科学家的薪资有何变化？"

公司调查：

• "伦敦哪些公司招聘的软件工程师最多？"
• "显示纽约金融类职位的顶级雇主"

工具详情

search_jobs

通过全面的筛选条件搜索职位：

Parameters:
- country (required): Country code (e.g., "gb", "us")
- keywords: Search terms (e.g., "python developer")
- location: City, region, or postal code
- page: Page number (starts at 1)
- results_per_page: Results per page (max 50)
- salary_min/salary_max: Annual salary filter
- full_time/part_time/contract/permanent: Job type filters
- category: Category tag from get_categories
- sort_by: "date", "salary", or "relevance"
- max_days_old: Maximum listing age in days

get_categories

搜索前获取有效的类别标签：

Parameters:
- country (required): Country code

Returns category tags like "it-jobs", "engineering-jobs", "finance-jobs"

get_salary_histogram

了解薪资分布：

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category

get_top_companies

查找主要雇主：

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category

get_geodata

比较各地区的薪资：

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Focus on sub-regions
- category: Filter by category

get_salary_history

分析薪资趋势：

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category
- months: Months of history (default 12, max ~24)

重要说明

• 薪资为年薪金额，以所选国家/地区的当地货币计价
• 先调用 get_categories，获取适用于所在国家/地区的有效类别标签
• 许多职位没有列出薪资——薪资筛选条件会排除这些职位
• 存在速率限制——Adzuna API 的免费层有使用限制

项目结构

adzuna-mcp/
├── server.py              # Main MCP server
├── pyproject.toml         # Package configuration
├── requirements.txt       # Python dependencies
├── .env.example           # Environment template
├── .env                   # Your credentials (gitignored)
├── tests/                 # Test suite
│   ├── __init__.py
│   └── test_server.py
├── .github/
│   └── workflows/
│       ├── ci.yml         # CI pipeline
│       └── publish.yml    # PyPI publishing
├── CONTRIBUTING.md        # Contribution guide
├── LICENSE
├── .gitignore
└── README.md

故障排除

Claude Desktop 中未显示服务

1. 检查配置中的 Python 路径是否正确
2. 确保虚拟环境已安装所有依赖项
3. 完全重启 Claude Desktop（Cmd+Q / Alt+F4）
4. 查看 Claude Desktop 日志：~/Library/Logs/Claude/mcp*.log

身份验证错误

1. 在 Adzuna Developer Portal 验证 API 凭据
2. 检查 .env 文件中的值是否正确
3. 确保环境变量已传递到 MCP 配置中

未返回结果

1. 尝试更宽泛的搜索词
2. 检查国家/地区代码是否有效
3. 移除薪资筛选条件（许多职位没有列出薪资）
4. 确认类别标签适用于该国家/地区

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT 许可证——详情请参阅 LICENSE。

致谢

• 感谢 Adzuna 提供职位搜索 API
• 感谢 FastMCP 提供 MCP 框架
• 感谢 Anthropic 制定 Model Context Protocol 规范