wallapop-cli MCP server

https://github.com/user-attachments/assets/015cb7d9-4363-4f9d-90e0-e6598e996f97

---

wallapop is a terminal cli for wallapop that lets you search with every filter the web has, watch searches, items, and sellers for changes, and chat with sellers, all from your own account. it compiles to one static Go binary. output is json by default so everything pipes into jq. --format pretty is for humans.

documentation | command demos | npm | github

why

if you already use wallapop and want it in the terminal, this cli gives you a practical path without the browser. search once and keep the results as a stream of events, talk to sellers from your own account, and use every filter the site offers, all from one static binary with no daemon. output is json by default, so scripts, agents, and shell pipelines all read the same thing.

quickstart

linux or macos

install the binary with curl:

curl -fsSL https://wallapop.micr.dev/install.sh | sh
wallapop --version

the installer places wallapop in ~/.local/bin (override with WALLAPOP_INSTALL_DIR).

windows

install via scoop:

scoop bucket add microck https://github.com/Microck/scoop-bucket
scoop install wallapop
wallapop --version

using a package manager

# homebrew
brew install Microck/tap/wallapop

# npm
npm install -g wallapop-cli

# arch linux (aur)
yay -S wallapop-cli-bin

go install

go install github.com/Microck/wallapop-cli/cmd/wallapop@latest
wallapop --version

release binaries include the pinned Galleton session engine; there is no separate install. go install source builds prepare that same pinned engine on their first authenticated use, using the Go toolchain and module cache (network is needed only if the module is not cached). For a fully bundled source build, clone this repository and run make install.

every release ships checksums.txt with a github provenance attestation:

gh release download --repo Microck/wallapop-cli --pattern checksums.txt
gh attestation verify checksums.txt --repo Microck/wallapop-cli

check that the install works:

wallapop --version
wallapop doctor

doctor checks that the config parses, shows the proxy in use, checks that the session mints, wallapop is reachable, and the cli can fetch the chat token.

auth

wallapop keeps your login in an http-only browser cookie, so the cli imports it instead of asking for a password. password, google, apple, and facebook accounts all work the same way.

1. log in at es.wallapop.com in your browser
2. export cookies with an extension such as cookie-editor, or copy the value of __Secure-next-auth.session-token
3. run wallapop auth login and paste the file path or the value, or pass --cookies FILE

the export can be a netscape cookies.txt, cookie-editor or editthiscookie json (array or {"url", "cookies"} wrapper), a devtools cookie list, a Cookie: header, or the bare cookie value. the format is detected (--cookies-format overrides it) and only wallapop.com cookies are read, so a whole-browser export works too.

# interactive prompt (paste cookie value or file path)
wallapop auth login

# import from an exported cookie file
wallapop auth login --cookies ~/Downloads/cookies.txt
wallapop auth login --cookies ~/Downloads/cookies.json

# read from stdin
cat cookies.txt | wallapop auth login --cookies-stdin

the cli imports the session and stores rotated credentials in a private encrypted vault. credentials.toml holds a session reference and account metadata, not the managed cookie. existing saved sessions migrate on their next authenticated use. your account location becomes the default search centre.

Wallapop can still expire or revoke a session, so you may need to log in again.

for renewal between commands, explicitly enable startup at OS login:

wallapop auth service enable
wallapop auth service status
wallapop auth service disable

wallapop auth service run is the foreground alternative for your own supervisor. the CLI never silently installs an OS startup service: after a successful wallapop auth login in a terminal it asks keep this login alive in the background? [Y/n], and yes runs wallapop auth service enable. --service / --no-service answer without asking (--service works with --no-input); --no-input, CI, WALLAPOP_SESSION_TOKEN and a non-terminal skip the question. without the service, wallapop auth status and wallapop doctor warn (without failing) when the imported session cookie expires within 48 hours. see session lifecycle and recovery.

check session status or verify credentials:

wallapop auth status
wallapop auth refresh

run multiple accounts side by side using profiles:

wallapop auth login --cookies alt.txt --profile alt
wallapop profile list
wallapop profile use alt
wallapop search "bici" --profile alt

for ci, pass WALLAPOP_SESSION_TOKEN in the environment so the cli writes no credentials file to disk:

export WALLAPOP_SESSION_TOKEN="..."
wallapop search "bici" --format jsonl

proxy

set proxy in config.toml or WALLAPOP_PROXY (socks5h://127.0.0.1:1080, http://host:port). all wallapop traffic then goes through it, session renewals included, and if it is unreachable the command fails with exit 6; it never falls back to a direct connection. config.toml is world-readable, so a proxy with credentials goes in WALLAPOP_PROXY only.

wallapop config set proxy socks5h://127.0.0.1:1080

when wallapop's cloudfront blocks a request (its 403 page, or a 429), the command exits 5 and the cli pauses session renewals for 15 minutes so they stop knocking from the same address. wallapop auth service status shows the pause. see session lifecycle and recovery.

updates

wallapop update
wallapop update --check
wallapop update --yes

eligible interactive commands check for a new stable release at most once a day and ask Update? [Y/n]. auth, watch, completion, help, and update are excluded from automatic checks. scripts, MCP, and --no-input never prompt or check automatically. set WALLAPOP_NO_UPDATE_CHECK=1 to disable automatic checks. npm, Homebrew, Scoop, and AUR installs update through their package manager; direct binaries use checksum-verified release archives. development and prerelease builds are not replaced.

auth model

credential	where it comes from	what it unlocks
none		search, item show, user *, category list, watches on public data
session cookie	browser export via auth login	favorites, own listings, chat, me *
WALLAPOP_SESSION_TOKEN	environment, for ci	same as above, never written to disk

command surface

command	what it does
auth login / status / refresh / logout	import, inspect, renew or forget a managed session
auth service enable / disable / status / run / stop	explicitly manage unattended renewal and inspect the bundled engine
profile list / use / remove	several accounts side by side
search [keywords] [--filter k=v]...	search around your location; search filters lists valid keys
category list	category ids
alert list	your saved searches on wallapop; watch add search --from-alert ID --name NAME turns one into a watch
item show / images / open / favorite / unfavorite	inspect a listing by hash or url
item reserve / reactivate / sold / delete	act on your own listings (reactivate relists an expired one; sold, delete ask or need --yes)
user show / items / reviews	look at a seller by hash, url or slug
me show / items / favorites	your account
chat list / show / send / start / open / archive	messaging; open is a live line-mode chat
watch add search|item|seller	create a watch (baselines silently, --emit-initial to report what exists)
watch check / run / events / list / remove	one-shot check, foreground loop, history
watch service install / uninstall / status	systemd user timer or launchd agent running watch check
sink list / test	notification targets from config
config path / get / set / list	config.toml
doctor	checks config, session, api, chat token, schedule
skills list / get	embedded docs for agents
completion bash|zsh|fish|powershell	shell completion

global flags: --profile, --format json|jsonl|pretty|toon, --no-color, --error-format text|json, --no-input, --debug.

shell completion

# zsh
wallapop completion zsh > "${fpath[1]}/_wallapop"

# bash
wallapop completion bash > /etc/bash_completion.d/wallapop

# fish
wallapop completion fish > ~/.config/fish/completions/wallapop.fish

# powershell
wallapop completion powershell >> $PROFILE

examples

wallapop search "thinkpad x1" --max-price 400 --sort newest --format pretty
wallapop search --category 100 --filter brand=Toyota --filter max_km=120000 --limit 20
wallapop item show https://es.wallapop.com/item/thinkpad-x1-carbon-1092837465
wallapop item images https://es.wallapop.com/item/thinkpad-x1-carbon-1092837465 --format pretty

wallapop watch add search "thinkpad x1" --max-price 400 --name x1 --notify phone
wallapop watch check --all --format jsonl | jq -r 'select(.type=="item.price_changed") | .item.url'
wallapop watch service install --interval 10m

wallapop chat list --unread --format pretty
wallapop chat start k2j3h4g5f6d7 "Hola, ¿sigue disponible?"
echo "Te lo dejo en 200" | wallapop chat send 8f1c2 -
wallapop chat open 8f1c2

what it looks like

these recordings use public listings. the watch writes only to its isolated local demo database. see the command demo gallery for search, filters, item details, and watch events.

inspect a listing

discover and apply category filters

track changes with a watch

Watches save a Search locally; each Check reports changes.

sinks config

a sink is a few lines of config:

[sinks.phone]
type = "ntfy"
url = "https://ntfy.sh"
topic = "wallapop-deals"

[sinks.discord]
type = "webhook"
url = "https://discord.com/api/webhooks/..."
template = "discord"

[sinks.script]
type = "exec"
command = ["~/bin/on-wallapop-event"]   # event json on stdin

exit codes

0 ok, 1 generic, 2 usage, 3 auth, 4 not found, 5 blocked or rate limited, 6 network, 7 wallapop changed its api. stderr carries a prefilled issue link. 130 interrupted.

building from source

git clone https://github.com/Microck/wallapop-cli && cd wallapop-cli
make build     # bin/wallapop
make check     # vet, staticcheck, tests, gofmt

documentation

full docs live at wallapop.micr.dev/docs. install, the cookie export walkthrough, the command reference generated from the binary, exit codes, sinks, and scheduling. the site source is in docs-site.

• docs/cli-spec.md: the interface contract and every endpoint the cli uses
• CONTEXT.md: vocabulary
• docs/adr: decisions

contributing

issues and pull requests are welcome. when wallapop changes something, the cli prints a prefilled issue link. that is the most useful report you can file.

disclaimer

this is an unofficial client. wallapop has no public api for buyers, and its terms of use prohibit bots, scraping and reverse engineering. the stated remedy is account suspension. use it with an account you are willing to lose, keep the check interval reasonable, and do not use it to spam sellers. not affiliated with wallapop.

license

mit license