kleinanzeigen-mcp
A read-only MCP server that lets an agent search public Kleinanzeigen.de listings and read individual listings via browser automation.
search_listings— keyword search with optionallocation(city or postal code),radiusKm(1–200),minPrice/maxPrice(EUR),sort(relevance,newest,price_asc,price_desc), andmaxPages(1–10, de-duplicated by listing id); returns{ results }of normalized summaries.get_listing— open a single listing byidor fullurland return its normalized details.Safe failures — errors come back as small payloads with codes like
CHALLENGE_REQUIRED,NAVIGATION_ERROR,LISTING_NOT_FOUND,RATE_LIMITED,INVALID_INPUT,INTERNAL_ERROR; no browser stack traces, no raw HTML.Read-only by design — public listings only: no login, no account features, no messaging, no CAPTCHA bypass, no proxy rotation, no bulk crawling.
Read-only access to public kleinanzeigen.de listings through a local browser session: search listings by query with optional location/radius, price range, sort order and multi-page walking, plus retrieval of a single listing's details by id or URL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kleinanzeigen-mcp search for a used Mac Mini M4 under 500 euros near Berlin"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
kleinanzeigen-mcp
Unofficial project. Not affiliated with, endorsed by, or connected to Kleinanzeigen. "Kleinanzeigen" is used only to describe what the software talks to. This software performs user-directed browser automation on publicly available listings — no account, no login.
A read-only Model Context Protocol server for public kleinanzeigen.de listings. It lets an AI agent search listings and read a single listing through a local browser session.
No AI, no chat UI, no cloud service, no login, no messaging.
Acceptable use
The tool reads public listings, one request at a time, on behalf of a single person. It deliberately does not:
log in, create accounts, or touch any account,
read inboxes, send messages, or manage saved searches,
solve or bypass CAPTCHAs, challenges or access controls,
rotate proxies or spoof fingerprints to evade blocks,
crawl or bulk-export listings.
Every action maps to one user request: one search, one listing. Searches are capped at 10 result pages. You are responsible for complying with the terms of service of any site you access through this software.
Related MCP server: marktplaats-mcp
Requirements
Node.js >= 20
Install
From npm:
npm install -g @washedguy/kleinanzeigen-mcp
npx patchright install chromiumOr from a checkout:
npm install
npx patchright install chromium
npm run buildThe browser runtime is Patchright,
a drop-in Playwright fork that closes Playwright's automation leaks
(Runtime.enable, navigator.webdriver). If a real Google Chrome is installed it
is used automatically for a more realistic fingerprint; override with
KLEINANZEIGEN_CHANNEL=chrome|msedge|bundled.
Configure the MCP client
The server speaks MCP over stdio.
{
"mcpServers": {
"kleinanzeigen": {
"command": "npx",
"args": ["-y", "@washedguy/kleinanzeigen-mcp"]
}
}
}From a checkout, point at the built entrypoint instead:
{
"mcpServers": {
"kleinanzeigen": {
"command": "node",
"args": ["/path/to/kleinanzeigen-mcp/dist/index.js"]
}
}
}Tools
Tool | Input | Returns |
|
|
|
|
|
|
sort is relevance (default), newest, price_asc or price_desc.
location takes a city or postal code and combines with radiusKm. maxPages
(1–10) walks the numbered result pages and de-duplicates by listing id. Note that
promoted "Top-Anzeigen" are pinned to the top and ignore sorting.
Errors
Failures come back as small, safe payloads — never browser stack traces:
{ "error": "CHALLENGE_REQUIRED", "message": "Kleinanzeigen presented a challenge (e.g. CAPTCHA). Try again later from a normal browser session." }Codes: CHALLENGE_REQUIRED, NAVIGATION_ERROR, LISTING_NOT_FOUND,
RATE_LIMITED, INVALID_INPUT, INTERNAL_ERROR.
Examples
const { results } = await searchListings({ query: "Mac Mini M4", maxPrice: 500, sort: "price_asc" });
const listing = await getListing({ id: results[0].id });How it works
MCP and browser automation are strictly separated: the MCP layer only validates inputs and formats outputs, and never touches the browser.
src/
├── index.ts # stdio entrypoint
├── mcp/ # tools, schemas, response shape
├── kleinanzeigen/ # browser session, page readers, parsing, domain models
└── types/ utils/Search results and listings are parsed from Kleinanzeigen's server-rendered HTML into domain models; raw HTML never reaches the MCP client.
Debugging
kleinanzeigen-mcp-debug # or: npm run debugOpens a visible browser and saves every page (and client-side route change) as
HTML plus an index.jsonl into ./debug-snapshots/. To capture from normal tool
calls instead:
KLEINANZEIGEN_SAVE_HTML=1 npm start
# or: KLEINANZEIGEN_SNAPSHOT_DIR=/tmp/ka-snaps npm run devSnapshots may contain public listing data and are git-ignored — do not commit them.
Development
npm run dev # stdio server with watch mode
npm run verify # typecheck + lint + tests (run before committing)
npm run check # Biome lint/format/import-sort (write)
npm run test # node:test via tsxLinting and formatting use a single dev dependency
(Biome); configuration is in biome.json.
Security
No login, credentials, cookies or tokens: the server only reads public pages.
Sessions are not persisted.
Challenges are never solved or bypassed: the server returns
CHALLENGE_REQUIRED.No proxy rotation, no account creation, no CAPTCHA solving, no bulk scraping.
Logs go to stderr only (stdout is the MCP transport).
Limitations
Read-only, public listings. No account features.
IP reputation is out of scope. If Kleinanzeigen temporarily blocks your IP range, wait it out and reduce request frequency.
Promoted listings appear above the requested sort order.
Author
Built and maintained by Jan Herklotz, washed.dev: websites and web apps from Wiesbaden.
Available Tools
2 toolsget_listingGet listingARead-only
Open a single Kleinanzeigen listing and return its normalized details. Provide either id or url. Read-only.
Inputs: id, url.
search_listingsSearch listingsBRead-only
Search Kleinanzeigen.de for listings and return normalized summaries. Read-only.
Inputs: query (required), sort, location, maxPages, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
search_listings and get_listing have clearly distinct purposes: one performs a query and returns multiple summaries, the other retrieves a single listing by id or URL. There is no overlap or risk of misselection.
Both tool names follow a consistent verb_noun snake_case pattern (search_listings, get_listing) and accurately reflect read-only behavior. The convention is predictable and unambiguous.
With only two tools, the surface feels thin for a marketplace MCP. While search and detail retrieval are core, the server lacks ancillary tools that would make it feel well-scoped (e.g., category browsing or seller info).
The core read-only workflow is covered: users can search listings and retrieve full details for a single listing. Minor gaps exist, such as accessing seller profiles or navigating categories, but agents can work around them for basic browsing.
Related MCP Connectors
Search and browse global classifieds across 80 markets. No auth required for read-only access.
Craigslist listings for AI agents: search by keyword, city, state and category; cars, rentals.
Classifieds for AI assistants: sell, buy, rent, hire and find local services, just by asking.
Search and discover local community listings, classifieds, services and events.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents like claude.ai to search online marketplaces (e.g., Facebook Marketplace) through your own logged-in browser, returning structured listings and details.-
- AlicenseAqualityBmaintenanceEnables AI agents to search and monitor Dutch and Belgian classifieds (Marktplaats and 2dehands) for listings, seller profiles, and categories.875 PyPI5MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search Kleinanzeigen listings by keyword, category, location, price and seller type, with extra server-side filtering for title matches and required or excluded terms. It also retrieves full ad details, downloadable photos for visual inspection, category attributes, and seller reputation information.5MIT
- AlicenseAqualityBmaintenanceEnables AI clients to search Avito listings by city, price, and sort order, inspect complete listing cards, and review seller ratings and recent feedback locally in read-only mode.10548 npmMIT