kleinanzeigen-mcp
Wraps Kleinanzeigen's internal mobile API to search classified listings and inspect them in detail. Supports keyword and category search with filters for attributes, location/radius or postcode, price range, offer/wanted, private/commercial, shipping and sorting, plus server-side refinement filters (title_only, require, exclude). Provides tools to fetch an ad's full description, attributes, precise location, images and seller details, download ad photos as image content for vision analysis, look up location/region ids, list category-specific attribute filters, and browse the category tree.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
An MCP server that lets an AI search Kleinanzeigen
listings and pull ad and seller details. It wraps the Kleinanzeigen Android
app's API (api.kleinanzeigen.de / gateway.kleinanzeigen.de) and returns the
important fields to the AI.
Highlights
Visual Listing Analysis
Downloads and analyzes the actual ad photos, allowing vision-capable AI to inspect an item's condition, wear, damage, completeness, and other visual details instead of relying only on the seller's description.Filters the API doesn't have
title_only,requireandexcludeare applied server-side here and page on automatically, so an AI gets the number of real matches it asked for instead of re-searching to work around accessories and wrong variants.From discovery to full inspection
Find relevant ads, then retrieve complete descriptions, itemised attributes, locations, seller reputation and all photos for a deeper analysis.
Related MCP server: marktplaats-mcp
Tools
Results come as compact JSON, and fields without a value are left out.
Search by free-text keyword and/or category (id or name; a name matches the
way a model writes it, so "Handys" finds "Handy & Telefon" and "Laptop" finds
"Laptops & Notebooks", and a miss suggests the closest categories). Filters for
category-specific attributes, location/radius or postcode, price range,
offer/wanted, private/commercial, shipping and "Direkt kaufen", plus sorting
and paging (rows up to 30).
Client-side filters, applied here over what Kleinanzeigen returns, paging on
until rows matches turn up or 250 ads were scanned:
title_only: every word ofquerymust be in the titlerequire: terms that must appear in title or description ("128gb" matches "128 GB" too). This is where specs belong: sellers write the same storage size several ways and often leave it out of the title.exclude: drop ads whose title carries these ("kabel" catches "Ladekabel", "pro" spares "Prozessor")
Paid "TOP" placements are left out unless include_top_ads=True. They sit
above any sort order and are mostly repair shops and buyers ("Ankauf"), not
the item. Each hit has a short url, whether it ships, and image_count.
total, next_page and has_more say where to continue.
Everything about one ad: full description, attributes by the label the ad page shows ("Zustand", "Speicher", ...), category, location, shipping options, the seller's rating and how many photos it has.
Download an ad's photos server-side (at most 10) and return them as real image content, so a vision-capable client sees the pictures instead of just URLs.
Name, private vs commercial, member-since date, ad counts, followers, reply
speed and Kleinanzeigen's reputation score. The profile half is guarded by
IP-range anti-fraud and can fail from VPN or datacenter addresses; partial
then says so and the reputation still comes back.
Look up location ids for the location_id filter by name prefix: states,
cities and districts. For a postcode, pass zip_code to the search instead.
The attribute filters the search's attributes argument takes for one
category, straight from Kleinanzeigen's own search-options schema. They narrow
far better than extra words in query: in "PC-Zubehör & Software" they cut a
search down to grafikkarten or mainboards outright.
Browse the category tree for the ids the search takes. The tree (159
categories) ships with the server in data/categories.json, so this costs no
request. It stops fairly high up: finer cuts like "Grafikkarten" are attribute
filters.
Setup
Requires Python 3.10+.
pip install -r requirements.txtWith uv you can skip this step: main.py
declares its own dependencies, so uv run main.py installs them on the fly.
Run
python main.pyThe server starts over streamable HTTP and prints where it's listening:
Starting kleinanzeigen-mcp server on http://127.0.0.1:8020/mcpPoint your MCP client at that URL. Host, port and path live at the top of
main.py; the port differs from geizhals-mcp (8000) and willhaben-mcp (8010),
so all three can run side by side.
For clients that start the server themselves, python main.py --stdio speaks
MCP over stdin/stdout instead. Nothing has to run in the background then.
Add it to Claude (and other MCP clients)
Clients that start their own servers use the stdio mode. Clients that connect
to a URL need python main.py running and take the URL it printed on startup.
Claude Code
One command, no config file. Claude Code starts the server itself:
claude mcp add kleinanzeigen -- python /path/to/kleinanzeigen-mcp/main.py --stdioOr connect to a server you already started with python main.py:
claude mcp add --transport http kleinanzeigen http://127.0.0.1:8020/mcpAdd --scope user to have it in every project instead of only the current one.
claude mcp list shows whether the connection came up, claude mcp remove kleinanzeigen takes it out again.
Cursor, Codex, VS Code and other JSON-config clients
Same URL, in the client's MCP config:
{
"mcpServers": {
"kleinanzeigen": {
"type": "http",
"url": "http://127.0.0.1:8020/mcp"
}
}
}Claude Desktop
Custom connectors (Settings > Connectors) connect from Anthropic's cloud, so they cannot reach a server running only on your own machine. Two ways around it:
Let Claude Desktop start it over stdio. Open Settings > Developer > Edit
Config, add the kleinanzeigen entry to claude_desktop_config.json and
restart Claude Desktop:
{
"mcpServers": {
"kleinanzeigen": {
"command": "python",
"args": ["C:\\path\\to\\kleinanzeigen-mcp\\main.py", "--stdio"]
}
}
}Use the full path to main.py (forward slashes on macOS/Linux). With uv
installed, "command": "uv" and "args": ["run", "/path/to/kleinanzeigen-mcp/main.py", "--stdio"] also takes care of the
dependencies.
Or expose the server (cloudflared, ngrok, or run it on a box with a public hostname) and add that HTTPS URL under Settings > Connectors > Add custom connector. That way the tools also work in claude.ai and the mobile apps. Anyone who finds the URL can use the server too, though, so put authentication in front of it.
Every tool is marked read-only, so clients that honour that hint won't ask before each call. In Claude Desktop you can also open Settings > Connectors > kleinanzeigen and set the tools' dropdown on the right to Always allow.
Notes
Search quirks worth knowing:
totalis capped at 10000 by Kleinanzeigen (so that value means "at least"), and a missingprice_amountmeans "zu verschenken" or "VB", seeprice_type.main.pyholds the MCP tools; thekleinanzeigen/package holds the API access and credential (api.py), title matching, the category tree and the result summaries.Results go out as compact JSON with empty fields left out, and what all tools share is said once in the server instructions instead of in every tool description. Both keep what the model has to read small.
data/categories.jsonis a flattened snapshot of Kleinanzeigen's category tree (title, id, children), built byscripts/build_categories.pyfrom the liveapi/categories.json(which ships the tree wrapped in JAXB envelopes and a single "Alle Kategorien" pseudo-root). Re-run it if Kleinanzeigen changes their categories.The badges read
coverage.jsonfrom thecoveragebranch.scripts/update_coverage.pyrefreshes it from Kleinanzeigen's public "Über uns" page, and a daily GitHub Action commits any change there, so the counts don't add a commit tomasterevery day.API details are documented in
search_api.md.This uses Kleinanzeigen's internal mobile API, not an official one. Be nice to it.
Tests
pip install pytest
pytestThe suite runs offline against a fake Kleinanzeigen and goes through a real
MCP client, stdio transport included. KLEINANZEIGEN_LIVE=1 pytest adds smoke
tests against the live API. CI runs the offline suite on every push and the
live tests once a day, which is what notices Kleinanzeigen changing its app API
or retiring the client credential.
Disclaimer
This is an independent, unofficial project and is not affiliated with, endorsed by, or connected to Kleinanzeigen or Adevinta. "Kleinanzeigen" and all related trademarks belong to their respective owners.
It's published for educational and research purposes only. It talks to Kleinanzeigen's internal API, which is not meant for public use and may break or change at any time. You are responsible for how you use it: respect Kleinanzeigen's Terms of Service, robots rules and applicable law, and don't hammer their servers.
License
MIT LICENSE. Provided "as is", without warranty.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Live kleinanzeigen.de search, ad, seller, category and location data for AI clients
Search and browse global classifieds across 80 markets. No auth required for read-only access.
AI marketplace: search, buy, sell across Amazon, eBay, AliExpress. 13 tools.
Classified ads from Kleinanzeigen (Germany) and second-hand items from Vinted's 27 country sites.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to search and view advertisements on Marktplaats.nl with extensive filtering options.521MIT
- AlicenseAqualityBmaintenanceEnables AI agents to search and monitor Dutch and Belgian classifieds (Marktplaats and 2dehands) for listings, seller profiles, and categories.875 PyPI5MIT
- AlicenseNot gradedqualityBmaintenanceSearch Kleinanzeigen.de, Germany's largest classifieds site, via MCP tools without API keys.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search willhaben.at marketplace listings and retrieve full ad details, using filters for category, condition, size, color, pattern, brand, and more.4MIT