mcp-stepstone
StepStone job search via MCP: reliable scraping, structured output, and smooth integration with agent frameworks.
Install / Use
claude mcp add kdkiss -- npx -y github:kdkiss/mcp-stepstoneIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of mcp-stepstone
mcp-stepstone scores 72/100 on our quality scale, 3852nd of 4,702 Development & Engineering skills we index.
Its MCP Server is 13 KB long, well organised into 45 sections with 16 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated about 13 months ago. Expect some instructions to reference tool versions or APIs that have since changed.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 73/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-11. Automated pattern scan on 2026-11-11. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
mcp-stepstone compared with similar skills
All 4 of these similar skills score higher than mcp-stepstone; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mcp-stepstone (this skill)by kdkiss | 72 | 10 | 13mo ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.6k | 9d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.7k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install mcp-stepstone?
- Run
claude mcp add kdkiss -- npx -y github:kdkiss/mcp-stepstone. The install tabs above show the steps for each supported agent. - Which AI agents does mcp-stepstone work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is mcp-stepstone safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 73/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is mcp-stepstone still maintained?
- The repository was last updated about 13 months ago. Expect some instructions to reference tool versions or APIs that have since changed.
Skill content
View source on GitHubStepstone 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
- Key Features
- Quick Start
- Configuration
- Usage
- Architecture Overview
- Local Development
- Testing
- Troubleshooting
- Contributing
- Support
- Version History
- 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
<details> <summary><strong>Option 1 · Install with Smithery (Recommended)</strong></summary>npx -y @smithery/cli install @kdkiss/mcp-stepstone --client claude
</details>
<details>
<summary><strong>Option 2 · Manual Setup</strong></summary>
# 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
</details>
<details>
<summary><strong>Option 3 · Docker</strong></summary>
# Build the image
docker build -t mcp-stepstone .
# Run the container
docker run -it --rm mcp-stepstone
</details>
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 to5; 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. Aliasqueryis also accepted.session_id(string, optional) – Explicit session identifier (auto-selects the most recent active session when omitted).
⚠️ Provide either
job_indexorjob_query. Supplying both prioritisesjob_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 │
└─────────────────────┘
- 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.
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
radiusor broadensearch_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:
- 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"); - Slow initialization – Increase client timeouts (example Smithery
mcp.jsonsnippet):{ "mcpServers": { "stepstone-job-search": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "initTimeout": 30000, "timeout": 60000 } } } - Endpoint mismatch – Confirm the server is reachable where the client
expects it (for example,
curl -v http://localhost:3000/mcp). If Smithery logs showHTTP 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
- Fork the
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
117.6kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.7kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
