Stepstone Job Search MCP Server

An Model Context Protocol (MCP) server that lets MCP-compatible clients search the German job portal Stepstone.de. The service exposes a pair of tools for running multi-term job searches and fetching rich job details so assistants such as Claude Desktop or Smithery can surface up-to-date vacancies.

---

Table of Contents

1. Key Features
2. Quick Start
3. Configuration
4. Usage
5. Architecture Overview
6. Local Development
7. Testing
8. Troubleshooting
9. Contributing
10. Support
11. Version History
12. License

---

Key Features

• 🔍 Multi-term Search – Concurrently queries Stepstone for every search phrase you supply and deduplicates duplicate postings.
• 📍 Location Targeting – Supports German postal codes with a configurable radius (1–100 km) for regional searches.
• 🧠 Session-aware Follow-ups – Saves results for one hour so you can request full job details later via get_job_details.
• 🛡️ Robust Validation – Defensive parameter validation, logging, and graceful error messages for malformed requests.
• 🐳 Container & CLI Friendly – Works as a plain Python process or inside Docker; integrates cleanly with Smithery and Claude Desktop.

ℹ️ Note: A Redis cache and other scaling features are mentioned as future enhancements. They are not enabled in the current release.

---

Quick Start

Prerequisites

• Python 3.8+
• pip
• Internet access to reach Stepstone.de when running real searches

Installation Options

Option 1 · Install with Smithery (Recommended)

npx -y @smithery/cli install @kdkiss/mcp-stepstone --client claude

Option 2 · Manual Setup

# Clone the repository
git clone https://github.com/kdkiss/mcp-stepstone.git
cd mcp-stepstone

# Install runtime dependencies
pip install -r requirements.txt

# (Optional) make the server script executable on Unix-like systems
chmod +x stepstone_server.py

Option 3 · Docker

# Build the image
docker build -t mcp-stepstone .

# Run the container
docker run -it --rm mcp-stepstone

---

Configuration

MCP Client Configuration

Smithery mcp.json

{
  "mcpServers": {
    "stepstone-job-search": {
      "command": "python",
      "args": ["/path/to/stepstone_server.py"],
      "description": "Search for job listings on Stepstone.de",
      "env": {
        "LOG_LEVEL": "INFO",
        "REQUEST_TIMEOUT": "10"
      }
    }
  }
}

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stepstone-job-search": {
      "command": "python",
      "args": ["/absolute/path/to/stepstone_server.py"],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "USER_AGENT": "MCP-Stepstone-Bot/1.0"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, ERROR).
REQUEST_TIMEOUT	10	Timeout (seconds) for outbound Stepstone HTTP requests and the upper bound for long-running tool calls (the server stops waiting shortly before this limit to avoid client timeouts).
USER_AGENT	Browser-like UA string	Custom User-Agent presented to Stepstone.de.
MAX_RETRIES	3	Retry attempts for failed HTTP calls.
CACHE_TTL	300	Placeholder for future in-memory caching feature.

---

Usage

Available Tools

search_jobs

Runs one or more keyword searches against Stepstone.

Parameters

• search_terms (array of strings, optional) – Search phrases to query. Defaults to ["fraud", "betrug", "compliance"].
• zip_code (string, optional) – German 5-digit postal code. Defaults to "40210" (Düsseldorf).
• radius (integer, optional) – Radius in kilometres around the postal code. Defaults to 5; must be between 1 and 100.

get_job_details

Fetches one stored job and enriches it with full description and metadata.

Parameters

• job_index (integer, optional) – 1-based index into the most recent session’s results.
• job_query (string, optional) – Fuzzy match against stored jobs. Alias query is also accepted.
• session_id (string, optional) – Explicit session identifier (auto-selects the most recent active session when omitted).

⚠️ Provide either job_index or job_query. Supplying both prioritises job_index.

Example Invocations

// Basic search
{
  "tool": "search_jobs",
  "parameters": {
    "search_terms": ["software engineer", "developer"]
  }
}

// Location constrained search
{
  "tool": "search_jobs",
  "parameters": {
    "search_terms": ["marketing manager", "digital marketing"],
    "zip_code": "10115",
    "radius": 15
  }
}

// Fetch job details by index
{
  "tool": "get_job_details",
  "parameters": {
    "job_index": 1
  }
}

// Fetch job details by query string
{
  "tool": "get_job_details",
  "parameters": {
    "job_query": "AML Specialist",
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Sample Output

Job Search Summary:
Search Terms: fraud analyst, compliance officer
Location: 60329 (±25km)
Total Jobs Found: 23
Session ID: 550e8400-e29b-41d4-a716-446655440000

--- Results for 'fraud analyst' ---

1. Senior Fraud Analyst - Digital Banking
   Company: Deutsche Bank AG
   Description: Join our fraud prevention team to analyze transaction patterns...
   Link: https://www.stepstone.de/stellenangebote--Senior-Fraud-Analyst-Frankfurt-Deutsche-Bank-AG--1234567

📋 Job Details: Senior Fraud Analyst - Digital Banking
🏢 Company: Deutsche Bank AG
📍 Location: Frankfurt am Main
💰 Salary: €65,000 - €85,000 per year
⏰ Employment Type: Full-time, Permanent

📝 Description:
Join our fraud prevention team to analyze transaction patterns and develop detection algorithms...

✅ Requirements:
  • Bachelor's degree in Computer Science, Finance, or related field
  • 3+ years experience in fraud detection or financial crime prevention
  • Strong analytical skills with SQL, Python, or R
  • Knowledge of AML regulations and compliance frameworks

---

Architecture Overview

┌────────────────────┐    ┌─────────────────────┐    ┌───────────────────┐
│    MCP Client      │ ──▶ │  MCP Stepstone      │ ──▶ │   Stepstone.de     │
│ (Claude/Smithery)  │    │      Server          │    │    Job Portal      │
└────────────────────┘    └─────────────────────┘    └───────────────────┘
                                │
                        ┌─────────────────────┐
                        │   Job Scraper       │
                        │ - URL Builder       │
                        │ - HTML Parser       │
                        │ - Data Cleaner      │
                        └─────────────────────┘

1. Request – MCP client sends tool invocation.
2. Validation – Inputs validated (terms, postal code, radius).
3. Search – URLs constructed and fetched concurrently.
4. Processing – HTML parsed and normalised job entries produced.
5. Sessioning – Results stored in memory for one hour for follow-up queries.
6. Response – Textual summary returned to the MCP client.
7. Details – get_job_details fetches the original job page and extracts specifics.

Key modules:

• StepstoneJobScraper – Builds search URLs, fetches and parses job listings.
• JobDetailParser – Scrapes detailed job pages for salary, requirements, etc.
• SessionManager – Stores search sessions, supports lookup by index or fuzzy match.
• stepstone_server.py – Registers MCP tools/resources and handles tool invocations.

---

Local Development

# Clone repository
git clone https://github.com/kdkiss/mcp-stepstone.git
cd mcp-stepstone

# Create & activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install dev tooling
pip install pytest pytest-asyncio black flake8

# Run formatter and linter
black stepstone_server.py
flake8 stepstone_server.py

Debug Fixtures

A lightweight HTTP server is included to serve bundled HTML fixtures. Start it when adjusting selectors or parsers:

python debug_server.py

Visit http://127.0.0.1:5000 to inspect the mocked Stepstone pages used in tests.

HTTP Transport Adapter

Some hosted MCP environments (such as Smithery) require an HTTP endpoint with liberal CORS headers instead of the default STDIO transport. The project ships a small Starlette-based adapter that exposes the existing server over the streamable HTTP protocol:

python stepstone_http_server.py

The server listens on 0.0.0.0:8000 by default and responds to preflight requests with Access-Control-Allow-Origin: *. Adjust the HOST and PORT environment variables when deploying to platforms that mandate specific interfaces or ports.

---

Testing

The test suite uses mocked network responses to avoid contacting Stepstone.de.

pip install -r requirements.txt pytest
pytest

To validate specific tool flows interactively, you can run stepstone_server.py directly or call handle_call_tool from a Python shell.

---

Troubleshooting

Server Won’t Start

python --version            # Expect 3.8+
pip list | grep -E "(requests|beautifulsoup4|mcp)"
ls -la stepstone_server.py   # Confirm execute permissions when running directly

No Jobs Returned

• Verify the postal code is a valid five-digit German PLZ.
• Increase radius or broaden search_terms.
• Confirm internet connectivity.
• Stepstone layout changes may require updating selectors—use the debug server to compare fixtures.

Import Errors

pip install -r requirements.txt
pip install --upgrade pip

Enable Verbose Logging

export LOG_LEVEL=DEBUG
python stepstone_server.py

Logs are emitted to stdout; integrate with your own logging infrastructure if desired.

Smithery Scanner Cannot Initialize Connection

If the Smithery CLI reports repeated HTTP error: This operation was aborted or McpError: MCP error -32001: Request timed out messages while scanning the server, the MCP process started successfully but the JSON-RPC handshake failed. Typical causes and remedies:

1. CORS headers missing – Ensure your HTTP transport returns permissive CORS headers:

   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
   res.setHeader("Access-Control-Allow-Headers", "Content-Type");

2. Slow initialization – Increase client timeouts (example Smithery mcp.json snippet):

   {
     "mcpServers": {
       "stepstone-job-search": {
         "type": "streamable-http",
         "url": "http://localhost:3000/mcp",
         "initTimeout": 30000,
         "timeout": 60000
       }
     }
   }

3. Endpoint mismatch – Confirm the server is reachable where the client expects it (for example, curl -v http://localhost:3000/mcp). If Smithery logs show HTTP POST → undefined, double-check the configured URL or transport binding.

When debugging, start the server manually via npx -y @smithery/cli serve to observe whether it exits early or logs binding issues.

---

Contributing

1. Fork the repository and create a feature branch: git checkout -b feature/my-change.
2. Implement your changes and add tests.
3. Run pytest and lint/format the code (black, flake8).
4. Open a pull request describing the change.

Coding guidelines:

• Follow PEP 8 and include type hints where practical.
• Document public functions with docstrings.
• Handle network and parsing errors defensively.

---

Support

• 📖 Consult this README for configuration and usage tips.
• 🧪 Use the debug server to inspect fixture HTML when selectors break.
• 🐛 File bugs or feature requests via GitHub Issues.
• 💬 Join the project’s Discord community (link forthcoming).

---

Version History

v1.2.0 (Current)

• Added get_job_details tool for follow-up queries.
• Introduced session management with one-hour TTL.
• Enhanced detail parsing for salary, requirements, and benefits.
• Summaries now include session IDs for easy follow-up.

v1.1.0

• Expanded documentation and usage examples.
• Added Docker support and environment variable configuration.
• Improved error handling and validation.

v1.0.0

• Initial release with multi-term job search and MCP compliance.

---

License

Distributed under the MIT License.

---

Made with ❤️ for the German job market.