Stepstone

AnModel Context Protocol (MCP)server that lets MCP-compatible clients search the German job portalStepstone.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.
- Key Features
- Quick Start
- Configuration
- Usage
- Architecture Overview
- Local Development
- Testing
- Troubleshooting
- Contributing
- Support
- Version History
- License

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

# 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

# Build the image docker build -t mcp-stepstone . # Run the container docker run -it --rm mcp-stepstone

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

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

Runs one or more keyword searches against Stepstone.

- 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 to5; must be between 1 and 100.

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

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

⚠️ Provide eitherjob_indexorjob_query. Supplying both prioritisesjob_index.

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

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

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

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

- 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.

# 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

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

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

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:

The server listens on0.0.0.0:8000by default and responds to preflight requests withAccess-Control-Allow-Origin: . Adjust theHOSTandPORTenvironment variables when deploying to platforms that mandate specific interfaces or ports.

pip install -r requirements.txt pytest pytest

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

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

export LOG_LEVEL=DEBUG python stepstone_server.py

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

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

When debugging, start the server manually vianpx -y @smithery/cli serveto observe whether it exits early or logs binding issues.
- Fork the repository and create a feature branch:git checkout -b feature/my-change.
- Implement your changes and add tests.
- Runpytestand lint/format the code (black,flake8).
- Open a pull request describing the change.

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

- 📖 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).

- Addedget_job_detailstool 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.

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

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

Adds powerful web scraping and search capabilities to LLM clients like Cursor and Claude.

Official OpenWeb Ninja MCP server connecting any AI agent to 40+ web data APIs for web search, e-commerce, local business, jobs, real estate, and finance data.

Integrate real-time Scrapeless Google SERP(Google Search, Google Flight, Google Map, Google Jobs....) results into your LLM applications. This server enables dynamic context retrieval for AI workflows, chatbots, and research tools.

Unified MCP server giving any AI agent access to 20+ social platforms, web search, scraping, and crypto data — one install, any MCP client.

MCP server for Al Jazeera 360 — Connect AI assistants to Al Jazeera's streaming catalog. Search, browse, and retrieve Arabic video content with direct watch links.

Scrapes and searches for products on Amazon.

An MCP server that connects AI agents to Amazon product, search, and review data across 20 marketplaces via the ChocoData Amazon Scraper API.

Interact with the Bilibili video website, enabling actions like searching for videos, retrieving video information, and accessing user data.

A Model Context Protocol (MCP) service that indexes and queries car-deal contexts - fast, flexible search for vehicle listings and marketplace data.