Labsco
kdkiss logo

Stepstone

★ 9

from kdkiss

Fetches job listings from Stepstone.de based on keywords and location parameters.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#scraping#devops#git#maps#marketing

Stepstone Job Search MCP Server

smithery badge

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.

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.

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.