fancyboi999/goofish-cli

What it is

goofish‑cli is a Python command‑line tool that wraps the core operations of the Chinese second‑hand marketplace Xianyu (also called Goofish). It lets a human or an AI‑agent (Claude Code, Cursor, OpenClaw, etc.) program‑matically publish items, manage listings, send and receive messages, and query the platform – all through a single, structured command set.

Why it matters for AI agents

The tool is built with an AI‑first design:

• Every command can output machine‑readable formats (json, yaml, csv, md, table).
• It registers itself as an MCP (Model Context Protocol) server, so agents can call the commands as “tools” (e.g., goofish_item_get).
• Five Claude Skills are bundled, letting Claude‑based agents automatically load domain‑specific knowledge (publishing, replying, risk‑guard, shop diagnosis, overview) without relying on zero‑shot prompting.
• OpenClaw can load the repository as a compatible plugin bundle, exposing the same commands to its own agent framework.

Core capabilities (17 commands)

Area	Example commands	What they do
Auth	goofish auth login <cookies.json>	Import a browser cookie file to create a session; auth status checks validity.
Items	goofish item get <id>	Retrieve item details. goofish item publish …
Media	goofish media upload <file>	Upload images to Xianyu’s CDN.
Category	goofish category recommend <title>	AI‑assisted category recommendation.
Location	goofish location default	Fetch the default shipping address.
Messaging	goofish message list-chats, goofish message send …, goofish message watch	List chats, send text/images, and keep a real‑time WebSocket stream of three event types (message, read, new_msg).
Search & View	goofish search items …, goofish item view …	Browser‑automated search (Playwright) and a full‑field “view” mode that bypasses anti‑spam limits.
Skills	goofish skills install	Install the five Claude skill bundles into ~/.claude/skills/.

Safety & compliance

• Rate‑limiting – per‑account caps (1 publish/min, 9 media uploads/min) and automatic circuit‑breaker (RGV587).
• Risk guard – built‑in checks for prohibited words, external links, and other platform‑specific red‑lines.
• Compliance notice – the README stresses that the tool is for personal‑account automation only; it must not be used for fraud, bulk‑selling SaaS, or to evade Xianyu’s user agreement.

Getting started (60 seconds)

pip install goofish-cli            # or: uv pip install goofish-cli
# Export your Xianyu cookies from Chrome DevTools → Application → Cookies
goofish auth login ~/Downloads/goofish-cookies.json
goofish auth status                # confirm login works
# Example actions
goofish item get 1045171414271
goofish message watch             # live IM feed
goofish message send <cid> <toid> --text "在的"

All commands accept --format json|yaml|table|md|csv for easy downstream parsing.

Integration steps for Claude Code (MCP)

1. Install the tool (as above).
2. Add an entry to ~/.config/claude-code/config.json:

   {"mcpServers": {"goofish": {"command": "uvx", "args": ["goofish-cli"]}}}
   

3. Claude will now expose functions like goofish_item_publish that you can invoke directly in a conversation.

OpenClaw / ClawHub usage

openclaw plugins install clawhub:openclaw-goofish
# optional: login via QR code
uvx --from goofish-cli==0.5.3 goofish auth login --qr
openclaw plugins inspect goofish --json
openclaw gateway restart

The plugin bundle provides the same MCP tools plus the five Claude skills.

Development & testing

• Uses uv for environment management (uv venv --python 3.11).
• 33 unit tests (pytest) and static analysis with ruff (zero warnings).
• Contributing guidelines and architecture docs are in the repo.

License

Apache 2.0 – free for personal and commercial use, with the usual attribution requirements.

---

Bottom line: goofish-cli is a fully‑featured, Python‑based automation layer for Xianyu that is deliberately engineered to be consumable by modern AI agents via MCP and Claude skills, while providing a human‑friendly CLI and safety mechanisms.