kleinanzeigen
# kleinanzeigen-lowballer
An MCP server for kleinanzeigen.de that lets the AI of your choice haggle for you: it searches, reads listings, writes to sellers and negotiates. Low opening offer, friendly tone, bounded persistence. The rules (your price limit, waiting times, how often it may nudge) are enforced by the server, not left to the model, and the server tells every client how to negotiate, so no extra prompt is needed.
Everything runs on your own machine: your IP, your Kleinanzeigen login, your negotiations. There is deliberately no hosted instance.
## Install
Needs Node.js 22 or newer. It starts in a dry run: search and listings are real, messages to sellers are only recorded locally.
| Client | Install |
|---|---|
| Cursor | [Add to Cursor](https://cursor.com/en/install-mcp?name=kleinanzeigen&config=eyJjb21tYW5kIjogIm5weCIsICJhcmdzIjogWyIteSIsICJnaXRodWI6c3Bla3VsYXphcnVzL2tsZWluYW56ZWlnZW4tbG93YmFsbGVyIl0sICJlbnYiOiB7IktBX0RSWV9SVU4iOiAiMSJ9fQ%3D%3D) |
| VS Code | [Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=kleinanzeigen&config=%7B%22command%22%3A%20%22npx%22%2C%20%22args%22%3A%20%5B%22-y%22%2C%20%22github%3Aspekulazarus/kleinanzeigen-lowballer%22%5D%2C%20%22env%22%3A%20%7B%22KA_DRY_RUN%22%3A%20%221%22%7D%7D) |
| Claude Code | `claude mcp add kleinanzeigen -e KA_DRY_RUN=1 -- npx -y github:spekulazarus/kleinanzeigen-lowballer` |
| Anything else (Claude Desktop, Hermes Agent, LM Studio, …) | add the JSON below to the client's MCP config |
```json
{
"mcpServers": {
"kleinanzeigen": {"command": "npx", "args": ["-y", "github:spekulazarus/kleinanzeigen-lowballer"], "env": {"KA_DRY_RUN": "1"}}
}
}
```
The first start takes a minute (npm fetches and builds the package). Then ask your AI, for example: "Suche ein MacBook Pro M3 Max mit 36 GB, mein Limit sind 1.900 €. Verhandle mit den drei besten Angeboten." Clients that support MCP prompts also offer the prompt `lowball`.
State lives per OS user in `~/.kleinanzeigen-lowballer/` (`KA_DATA_DIR` overrides it). Settings come from the MCP client's `env` or from `~/.kleinanzeigen-lowballer/.env`.
## How it is built
```
any MCP client (Claude, Cursor, Hermes Agent, …)
│ MCP (stdio), server instructions = src/persona.ts
src/server.ts ── src/service.ts ── src/policy.ts rules, pure functions
│ └──────── src/store.ts ~/.kleinanzeigen-lowballer/state.json
├── src/kleinanzeigen/public.ts + parse.ts search + listings, plain HTTP, no login
├── src/kleinanzeigen/polite.ts throttle, cache, back-off
└── src/kleinanzeigen/session.ts contact form + inbox, logged-in Chromium profile
```
## Development
```bash
git clone https://github.com/spekulazarus/kleinanzeigen-lowballer && cd kleinanzeigen-lowballer
npm ci
npm test
npm run mcp # the server from source; reads .env in the checkout (cp .env.example .env)
```
## Example: Hermes Agent with GLM 5.3 on T-Systems AIFS
`hermes/` holds a ready [Hermes Agent](https://hermes-agent.nousresearch.com/docs) setup for a checkout. Set `AIFS_API_KEY` in `.env`, check it with `npm run aifs:check` (key, endpoint, model id, tool calling), install Hermes Agent as its docs describe, then:
```bash
bin/lowball # chat
bin/lowball -z "Suche ein MacBook Pro M3 Max mit 36 GB, mein Limit sind 1.900 €. Verhandle mit den drei besten Angeboten."
```
`bin/lowball` exports `.env`, points `HERMES_HOME` at `hermes/` and starts `hermes`. For the routine check (replies, follow-ups) Hermes' scheduler needs its gateway running:
```bash
bin/lowball cron create "every 2h" "Kleinanzeigen-Routine: check_inbox. Für jede neue Verkäufer-Nachricht einen Antwortentwurf mit draft_message anlegen und mir Nachricht und Entwurf schicken. Nichts ohne mein Ja senden." --name lowball-loop
bin/lowball gateway run
```
AIFS is moving to a new API ([transition guide](https://docs.llmhub.t-systems.net/api-transition/)): new `https://llm-server.ai.t-systems.net/v1` (used here), legacy `https://llm-server.legacy.ai.t-systems.net/v2`; the old host `llm-server.llmhub.t-systems.net` is switched off at the end.
## Dry run and going live
`KA_DRY_RUN=1` (default): search and listings are real, messages are only written to `~/.kleinanzeigen-lowballer/state.json`. The extra tool `simulate_seller_reply` plays the seller, so a whole negotiation can be rehearsed.
Live:
```bash
npx playwright install chromium
npx -y github:spekulazarus/kleinanzeigen-lowballer login # in a checkout: npm run login
```
Log in by hand in the window that opens; the session stays in `~/.kleinanzeigen-lowballer/browser-profile`. Then set `KA_DRY_RUN=0` in the client's `env`.
The live message path (`src/kleinanzeigen/session.ts`) has never run against a real account. The contact form fields are taken from the public listing page; the inbox routes (`/m-access-token.json`, `gateway.kleinanzeigen.de/messagebox/api/…`) are written from memory. Expect to adjust them on the first live run; errors quote the server's answer.
Kleinanzeigen's terms forbid automated use of the site. An account that sends messages through this can be blocked. Use a second account, and keep the limits low.
## You confirm every message, and it learns from your corrections
By default (`KA_REQUIRE_APPROVAL=1`) the assistant cannot send on its own. It writes a draft (`draft_message`), shows you the seller's message and its answer, and asks. "Ja" sends it (`send_draft`); anything like "freundlicher" or "biete 10 € mehr" produces a new draft. A draft is dropped when the seller writes again in the meantime.
What you correct is kept in `~/.kleinanzeigen-lowballer/style.json` and handed to the assistant with every drafting step, whichever AI you use:
- corrected drafts: its version, your feedback, the text that went out (the latest 15),
- lasting preferences it saves with `remember_preference` when your feedback is meant generally ("immer siezen"). `get_style` shows them, `forget_preference` removes one.
The confirmation is a rule the server gives the assistant plus a two-step send, not a lock: the server cannot see whether a human really said yes. The price limit, waiting times and caps below are enforced either way.
To be notified about new seller messages, let your agent run the routine check on a schedule and report to you. With Hermes Agent and a connected messenger:
```bash
hermes cron create "every 2h" "Kleinanzeigen-Routine: check_inbox. Für jede neue Verkäufer-Nachricht einen Antwortentwurf mit draft_message anlegen und mir Nachricht und Entwurf schicken. Nichts ohne mein Ja senden." --name lowball-loop
```
## Teaching it your own style
`npm run export-history` (after `npm run login`; optional number = how many conversations, default 100) writes your past Kleinanzeigen conversations to `~/.kleinanzeigen-lowballer/history.json`. It works in the dry run too, because it only reads. The file contains other people's messages: keep it local, never commit it. It is the input for adapting `src/persona.ts` to how you actually negotiate.
## Rules the server enforces
The model writes the messages; `src/policy.ts` decides whether they go out. A refusal comes back as `{ "refused": "<code>", "message": …, "retry_at": … }`.
| Rule | Default | Env |
|---|---|---|
| Offer never above the buyer's limit (or the asking price), never below an earlier offer | | |
| Lowest offer, share of the asking price | 0.5 | `KA_MIN_OFFER_RATIO` |
| Suggested opening offer | 0.7 | `KA_OPENING_RATIO` |
| Nudges without an answer, then the negotiation is given up | 2 | `KA_MAX_FOLLOWUPS` |
| Wait before a nudge | 24 h | `KA_FOLLOWUP_MIN_HOURS` |
| Messages per negotiation | 8 | `KA_MAX_MESSAGES` |
| New sellers per day | 10 | `KA_MAX_NEW_PER_DAY` |
| No messages at night (Europe/Berlin) | 22–8 | `KA_QUIET_HOURS` |
| The message must name the offer and must not name the limit | | |
| A seller who asks not to be written to again closes the negotiation for good | | |
| An unread seller reply blocks sending until it has been read | | |
## Load on kleinanzeigen.de
`src/kleinanzeigen/polite.ts` keeps the request count low instead of hiding it: one request at a time with a 4–6 s pause, a 10-minute cache for searches and listings, at most 120 requests per hour, and after a 403/429/503 no requests at all for 30 minutes (doubling up to 12 h, `Retry-After` respected). The block and the budget survive restarts in `~/.kleinanzeigen-lowballer/http.json`. Tools answer `{ "refused": "slow_down", "retry_at": … }` in that case. Tune with `KA_REQUEST_INTERVAL_S`, `KA_MAX_REQUESTS_PER_HOUR`, `KA_CACHE_MINUTES`.
## Tools
`search_listings`, `get_listing`, `start_negotiation`, `draft_message`, `send_draft`, `discard_draft` (or `send_message` with `KA_REQUIRE_APPROVAL=0`), `remember_preference`, `forget_preference`, `get_style`, `check_inbox`, `list_negotiations`, `get_negotiation`, `close_negotiation`, `status`, `report_problem`, and in the dry run `simulate_seller_reply`.
## Something broken? An idea?
Tell your assistant: "Das funktioniert nicht, melde das." The tool `report_problem` drafts the report in the project's format, strips contact data, tokens and ad ids, and returns a link to a pre-filled GitHub issue. Nothing is sent by the server; you submit it with your own GitHub account after reading it. Fixes are welcome as pull requests: [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[PolyForm Noncommercial 1.0.0](LICENSE.md): use, change and share it for any noncommercial purpose. Commercial use is not permitted.
Required Notice: Copyright spekulazarus (https://github.com/spekulazarus/kleinanzeigen-lowballer)
TDQS
Scored across 16 tools
Most tools target clearly distinct actions: search_listings vs. get_listing, draft_message vs. send_draft vs. discard_draft, and the preference tools are separate. check_inbox and list_negotiations overlap in showing negotiations with next steps, and get_style uses different terminology from remember_preference/forget_preference, but the descriptions mostly resolve the boundaries.
All names use snake_case and most follow a clear verb_noun pattern (list_negotiations, get_listing, send_draft). The main deviations are the bare-noun status and the inconsistent preference vocabulary (get_style vs. remember_preference/forget_preference), but the overall convention is readable.
16 tools is slightly above the typical 3–15 range, but the domain genuinely needs search, listing details, negotiation lifecycle, drafting/sending, preference memory, status, simulation, and reporting. No tool is obviously redundant, though the set is close to feeling heavy.
The surface covers search, listing details, negotiation creation/listing/detail/closing, message drafting/sending/discarding, preference memory, status, simulation, and problem reporting. Minor gaps remain, such as changing the hard price limit after start_negotiation or reopening a closed negotiation, but core workflows are covered.