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 開發人員職位"
• "顯示德國的數據科學職位"

薪資研究

• "英國機器學習工程師的典型薪資是多少？"
• "比較倫敦和曼徹斯特的軟件工程師薪資"
• "過去一年數據科學家的薪資有何變化？"

公司研究

• "倫敦哪些公司招聘的軟件工程師最多？"
• "顯示紐約金融職位的頂級僱主"

📚 詳細文檔

支持的國家

可用工具

工具詳情

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 提供模型上下文協議規範。