Stepstone

You can run an MCP server that lets clients search the Stepstone.de job portal with multi-term queries, fetch rich job details, and keep results session-aware for follow-up requests. This guide walks you through using, installing, and configuring the Stepstone MCP Server so you can surface up-to-date vacancies to assistants and clients.

How to use

You use this MCP server by loading it into an MCP client and invoking tools to search for jobs and fetch details. Start with a multi-term search to query Stepstone.de for several phrases at once, then request detailed information for a chosen result. The server validates inputs, deduplicates postings, and stores a one-hour session for follow-up queries like get_job_details. Use location targeting by providing a German ZIP code and a radius to constrain results geographically.

How to install

Prerequisites you need before installing the MCP server: Python 3.8 or newer and pip. You also need internet access to reach Stepstone.de when performing real searches.

# Option A: Install with Smithery (Recommended)

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

# Option B: 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 C: Docker

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

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

Configuration

Configure how you run the server from MCP clients and set environment controls to tailor behavior.

{
  "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"
      }
    }
  }
}

Usage tips and notes

The server exposes tools to perform actions and manage sessions. Use search_jobs to perform multi-term searches with optional ZIP code and radius parameters. Use get_job_details to fetch full descriptions and metadata for a stored job by index or query. Maintain awareness that the session results are stored for one hour to enable follow-up without repeating the search.

Local development

To contribute or customize locally, you can run a development workflow that mirrors typical Python projects.

# 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

Testing and debugging

Tests use mocked responses to avoid real network calls. Run tests with pytest to verify behavior and then execute the server script directly for interactive validation.

pip install -r requirements.txt
pytest

Troubleshooting

If the server doesn’t start, verify Python version and essential packages, and check the permissions on the server file. If no jobs are returned, ensure the postal code is valid, radius is reasonable, and internet access is available. If selector changes occur in Stepstone pages, use the debug fixtures to compare expected HTML.

Notes on deployment options

Two common deployment approaches are supported: running the Python server directly or running it inside a Docker container. The Python approach uses a direct command to execute the server script, while the Docker approach builds and runs a container image named mcp-stepstone.

# Docker run example

docker run -it --rm mcp-stepstone

Tools exposed by this server

The server provides two primary tools: search_jobs for multi-term job searches against Stepstone.de, and get_job_details to enrich a stored job with full description and metadata.

Available tools

search_jobs

Runs multi-term searches against Stepstone.de and deduplicates results.

get_job_details

Fetches full job descriptions and metadata for a stored result.