SkillAgentSearch skills...

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

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

72/100

Supported Platforms

Claude Code
Claude Desktop

Tags

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.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
4/20
Freshness
5/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
mcp-stepstone (this skill)by kdkiss721013mo agoMCP Server
taste-skillby Leonxlnx100117.6k9d agoCLAUDE.md
Agent-Reachby Panniantong100112.7k9d agoCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10079.9ktodayCLAUDE.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.

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.


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

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars10
CategoryDevelopment
Updated1y ago
Forks2

Languages

HTML

Trust signals

73/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

2 medium1 info