adzuna-job-search-mcp

🚀 Adzuna Jobs MCP 服务器

Adzuna Jobs MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它为 AI 助手提供了访问 Adzuna 职位搜索 API 的能力。借助该服务器，用户可以在 12 个国家搜索职位、分析薪资数据以及研究雇主信息。

🚀 快速开始

前提条件

• Python 3.10 及以上版本
• Adzuna API 凭证（免费）

获取 Adzuna API 凭证

1. 访问 Adzuna 开发者门户。
2. 注册一个免费账户。
3. 创建一个新应用程序。
4. 复制你的 应用 ID 和 应用密钥。

安装

选项 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  # 在 Windows 上：venv\Scripts\activate
pip install -e ".[dev]"

配置环境变量

创建一个 .env 文件，并填入你的 Adzuna 凭证：

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 客户端配合使用

直接运行服务器：

# 激活虚拟环境
source venv/bin/activate

# 使用标准输入输出传输（默认）运行
python server.py

# 或者使用 FastMCP CLI
fastmcp run server.py:mcp

开发模式

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

fastmcp dev server.py

这将打开一个基于浏览器的 UI 来测试你的工具。

✨ 主要特性

• 职位搜索 - 可使用地点、薪资、职位类型等过滤器搜索数百万个职位列表。
• 薪资分析 - 获取薪资直方图、地区比较和历史趋势。
• 公司研究 - 按招聘数量查找顶级雇主。
• 多国家支持 - 支持 12 个国家的就业市场，并提供当地货币支持。

📦 安装指南

选项 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  # 在 Windows 上：venv\Scripts\activate
pip install -e ".[dev]"

配置环境变量

创建一个 .env 文件，并填入你的 Adzuna 凭证：

ADZUNA_APP_ID=your_app_id_here
ADZUNA_APP_KEY=your_app_key_here

💻 使用示例

示例提示

连接服务器后，你可以向 AI 助手提出以下问题：

职位搜索

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

薪资研究

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

公司研究

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

📚 详细文档

支持的国家

| 代码 | 国家 | 货币 | |------|---------|----------| | gb | 英国 | 英镑 £ | | us | 美国 | 美元 $ | | de | 德国 | 欧元 € | | fr | 法国 | 欧元 € | | au | 澳大利亚 | 澳元 $ | | nz | 新西兰 | 新西兰元 $ | | ca | 加拿大 | 加元 $ | | in | 印度 | 印度卢比 ₹ | | pl | 波兰 | 波兰兹罗提 zł | | br | 巴西 | 巴西雷亚尔 R$ | | at | 奥地利 | 欧元 € | | za | 南非 | 南非兰特 R |

可用工具

| 工具 | 描述 | |------|-------------| | search_jobs | 使用过滤器（关键词、地点、薪资、职位类型）搜索职位 | | get_categories | 获取某个国家的有效职位类别标签 | | get_salary_histogram | 获取职位搜索的薪资分布数据 | | get_top_companies | 按开放职位数量获取顶级雇主 | | get_geodata | 获取按地理区域划分的薪资数据 | | get_salary_history | 获取薪资的历史趋势 | | get_api_version | 获取当前 Adzuna API 版本 |

工具详情

search_jobs

使用全面的过滤器搜索职位：

参数:
- country（必需）: 国家代码（例如，"gb", "us"）
- keywords: 搜索词（例如，"python developer"）
- location: 城市、地区或邮政编码
- page: 页码（从 1 开始）
- results_per_page: 每页结果数（最多 50）
- salary_min/salary_max: 年度薪资过滤器
- full_time/part_time/contract/permanent: 职位类型过滤器
- category: 从 get_categories 获取的类别标签
- sort_by: "date", "salary", 或 "relevance"
- max_days_old: 列表的最大天数

get_categories

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

参数:
- country（必需）: 国家代码

返回类别标签，如 "it-jobs", "engineering-jobs", "finance-jobs"

get_salary_histogram

了解薪资分布：

参数:
- country（必需）: 国家代码
- keywords: 按职位类型过滤
- location: 按地点过滤
- category: 按类别过滤

get_top_companies

查找主要雇主：

参数:
- country（必需）: 国家代码
- keywords: 按职位类型过滤
- location: 按地点过滤
- category: 按类别过滤

get_geodata

比较不同地区的薪资：

参数:
- country（必需）: 国家代码
- keywords: 按职位类型过滤
- location: 关注子区域
- category: 按类别过滤

get_salary_history

分析薪资趋势：

参数:
- country（必需）: 国家代码
- keywords: 按职位类型过滤
- location: 按地点过滤
- category: 按类别过滤
- months: 历史月份数（默认 12，最多约 24）

🔧 技术细节

项目结构

adzuna-mcp/
├── server.py              # 主 MCP 服务器
├── pyproject.toml         # 包配置
├── requirements.txt       # Python 依赖项
├── .env.example           # 环境模板
├── .env                   # 你的凭证（git 忽略）
├── tests/                 # 测试套件
│   ├── __init__.py
│   └── test_server.py
├── .github/
│   └── workflows/
│       ├── ci.yml         # CI 管道
│       └── publish.yml    # PyPI 发布
├── CONTRIBUTING.md        # 贡献指南
├── LICENSE
├── .gitignore
└── README.md

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

重要提示

⚠️ 重要提示

• 薪资为所选国家当地货币的年度金额。
• 请先调用 get_categories 以获取你所在国家的有效类别标签。
• 许多职位未列出薪资，薪资过滤器将排除这些职位。
• Adzuna API 的免费套餐有使用限制。

故障排除

Claude Desktop 中未显示服务器

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

认证错误

1. 在 Adzuna 开发者门户 验证你的 API 凭证。
2. 检查 .env 文件中的值是否正确。
3. 确保在 MCP 配置中传递了环境变量。

未返回结果

1. 尝试使用更宽泛的搜索词。
2. 检查国家代码是否有效。
3. 移除薪资过滤器（许多职位未列出薪资）。
4. 验证类别标签对该国家是否有效。

贡献

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

致谢

• Adzuna 提供职位搜索 API。
• FastMCP 提供 MCP 框架。
• Anthropic 提供模型上下文协议规范。