ai-marketplace-monitor 0.10.13

An intelligent tool that monitors Facebook Marketplace listings using AI to help you find the best deals. Get instant notifications when items matching your criteria are posted, with AI-powered analysis of each listing.

📚 Read the Full Documentation

aimm runs in a terminal or in its web UI, which starts with it:

Command line: each search, the listings it skips or excludes, and the AI's verdict on each new listing

Web UI: the config editor, the Configure chat that sets aimm up for you, and the listings aimm evaluated with their AI ratings; it also shows the live log and aimm's browser when Facebook asks for a check (see Web UI)

Example notification from PushBullet:

Found 1 new gopro from facebook
[Great deal (5)] Go Pro hero 12
$180, Houston, TX
https://facebook.com/marketplace/item/1234567890
AI: Great deal; A well-priced, well-maintained camera meets all search criteria, with extra battery and charger. Seller is reputable, rated 5.0 out of 5 by 37 buyers.

What's New

• Seller reputation: aimm evaluates each seller, from how long they have been on Facebook, their listings and sales, their rating and what buyers say in reviews, and the AI identifies unreliable and malicious sellers automatically: new accounts, dealers posing as private sellers, bait listings, no-shows. Its rating and notifications tell you why. See Seller information.
• Guided Facebook login: aimm types your Facebook username and password, then waits for you to complete any CAPTCHA or security code before it searches. In Docker, the web UI shows a banner with an Open browser button. See Run the Monitor.
• AI-assisted configuration: aimm configure guides users through AI services, marketplace searches, items, notifications, regions, translations, and monitor settings without hand-writing TOML.
• UnitySVC for AI and notifications: Use one UnitySVC key for almost arbitrary AI models and 100+ notification channels. See AI Services and UnitySVC notification.
• Built-in Web UI: Edit config, add AI backends, and monitor live logs from your browser — starts automatically with the monitor. See Web UI documentation.

Table of Contents:

• What's New
• ✨ Key Features
• 🚀 Quick Start
• 💡 Example Usage
• 📚 Documentation
• 🤝 Contributing
• 📜 License
• 💬 Support
• 🙏 Credits

✨ Key Features

🔍 Smart Search

• Search multiple products using keywords
• Filter by price and location
• Exclude irrelevant results and spammers
• Support for different Facebook Marketplace layouts

🤖 AI-Powered

• Intelligent listing evaluation
• Smart recommendations
• AI-assisted configuration editing with aimm configure and the Web UI Configure chat
• Almost arbitrary AI models through UnitySVC, plus OpenAI, Anthropic, DeepSeek, Gemini, and Ollama
• Self-hosted model option through Ollama

📱 Notifications

• 100+ notification channels through UnitySVC
• PushBullet, PushOver, Telegram, and Ntfy notifications
• HTML email notifications with images
• Customizable notification levels
• Repeated notification options
• Optional daily digest (digest_at) of searches, matches and rejected listings: the full digest by email, a short summary on push channels

🖥️ Web UI

• Built-in config editor with TOML syntax highlighting
• Live log streaming and filtering
• A Listings table of every listing aimm evaluated, with its AI rating and why it was notified, rejected, or excluded
• Add, edit, and delete config sections from your browser
• No password required on localhost

🌎 Location Support

• Multi-city search
• Pre-defined regions (USA, Canada, etc.)
• Customizable search radius
• Flexible seller location filtering

🚀 Quick Start

⚠️ Legal Notice: Facebook's EULA prohibits automated data collection without authorization. This tool was developed for personal, hobbyist use only. You are solely responsible for ensuring compliance with platform terms and applicable laws.

Installation

Requires Python 3.10 or higher. Check your version with python --version. If your system default is older, use pip3.10 (or pip3.11, pip3.12, etc.) instead of pip, or create a virtual environment with the correct version.

pip install ai-marketplace-monitor
playwright install

Configure with AI

Most users do not need to write a configuration file by hand. Set one AI provider key, then let aimm configure create or update ~/.ai-marketplace-monitor/config.toml through a guided conversation:

export OPENAI_API_KEY='your_openai_key'
# or: export ANTHROPIC_API_KEY='your_anthropic_key'
# or: export UNITYSVC_API_KEY='your_unitysvc_key'

# aimm searches only while logged in to Facebook
export FACEBOOK_USERNAME='you@example.com'
export FACEBOOK_PASSWORD='your_facebook_password'

aimm configure

aimm reads your Facebook username and password from FACEBOOK_USERNAME and FACEBOOK_PASSWORD (or from username and password in [marketplace.facebook]). They are required: aimm does not search without logging in.

aimm configure checks or creates the AI setup first, then asks what you want to configure: marketplace searches, items to watch, notifications, regions, translations, or monitor settings. It explains proposed changes and asks before writing them.

You can also jump directly to one section:

aimm configure ai
aimm configure marketplace
aimm configure item.gopro

Here is a real session that adds an item. aimm configure starts with a summary of what is already configured and what is still missing, drafts the item from one plain-language request, and shows the change before writing it:

$ aimm configure
Using [ai.anthropic].
Thinking...
AIMM: Hi! You have two AI services (Anthropic, and UnitySVC with qwen3.7-flash), a Facebook
Marketplace search around Houston, and notifications to you (user "me") via UnitySVC. The one thing
still missing is an item to search for, so aimm can't monitor anything yet. Want to start by adding
one?

You can say things like "I want to add an item" (e.g. "watch for a GoPro under $200"), "update my
marketplace settings", or "what can I configure?".
You: I want to watch for an action camera: a GoPro Hero 9 or newer, a DJI Osmo Action 3 or newer,
or an Insta360 X3, X4 or Ace Pro. Used is fine if it works, with no water damage and no scratched
lens. Preferably under $250. Same Houston area, check every 30 minutes.
Thinking...
Thinking...
Thinking...
Thinking...
New item "action_camera": GoPro Hero 9+, DJI Osmo Action 3+, Insta360 X3/X4/Ace Pro; used OK if
working, no water damage or scratched lens; max $250; checked every 30 minutes; Houston area (20
miles) from your existing marketplace.

 [item.action_camera]
 request = "Watch for an action camera (GoPro Hero 9+, DJI Osmo Action 3+, Insta360 X3/X4/Ace Pro),
 used OK if working, no water damage or scratched lens, preferably under $250, in the Houston area,
 checked every 30 minutes."
 search_phrases = ["gopro hero", "dji osmo action", "insta360 x3", "insta360 x4", "insta360 ace pro",
 "action camera"]
 description = "Action camera: GoPro Hero 9 or newer, DJI Osmo Action 3 or newer, or Insta360 X3,
 X4 or Ace Pro. Used is fine if it works. No water damage and no scratched lens."
 keywords = ["gopro", "go pro", "dji", "osmo", "insta360"]
 max_price = "250"
 search_interval = "30m"

 (a diff of ~/.ai-marketplace-monitor/config.toml follows)

Write these changes? [Y/n] y
Saved ~/.ai-marketplace-monitor/config.toml.
Thinking...
AIMM: I've saved the action camera item. It covers GoPro Hero 9+, DJI Osmo Action 3+ and Insta360
X3/X4/Ace Pro. It accepts used cameras that work, with no water damage or scratched lens. The price
limit is $250, and it's checked every 30 minutes in your Houston area (20 miles). I set the price as
a hard limit. I can't make it a soft preference.

Is there anything else you'd like to change?
You: No, that's all. Thanks.
Thinking...
AIMM: All done. Enjoy the hunt!
Your configuration is saved, but nothing is searching yet: run `aimm run` to start monitoring (a
monitor that is already running picks up the change on its own).

Run the Monitor

aimm

What happens next:

1. aimm opens a browser window, goes to Facebook, and types your username and password.
2. If Facebook asks for a CAPTCHA or a security code, complete it in that window. aimm waits as long as it takes (the web UI shows a "waiting for Facebook login" banner) and reminds you in the log every few minutes.
3. Once you are logged in, aimm searches Facebook Marketplace and notifies you of matching items. If Facebook logs it out later, it waits for you the same way.

A web UI also starts automatically at http://127.0.0.1:8467 for editing config and monitoring logs — see Web UI Guide. aimm is the same as aimm run; ai-marketplace-monitor provides the same interface.

You never need to restart aimm to change your configuration. Save the config file, in the web UI, with aimm configure or in any editor, and the running monitor picks up the change on its own: after the current search it reloads the configuration and searches all items with it. The ⏸ button in the web UI stops the monitor only when you need its browser to yourself, and ▶ starts it again.

aimm always shows its browser, because Facebook may ask you to complete a CAPTCHA or a security code. To run aimm on a server, a NAS or another machine without a screen, use the Docker image: it has a virtual display, and the web UI shows you its browser when you need it.

Run with Docker

A prebuilt image on GitHub Container Registry runs aimm on a server, a NAS or macOS. It has a virtual display, and the web UI shows you its browser when Facebook asks for a CAPTCHA or a security code.

docker run -d --name aimm \
  -p 8467:8467 \
  -v "$HOME/.ai-marketplace-monitor:/data" \
  -e FACEBOOK_USERNAME -e FACEBOOK_PASSWORD \
  -e UNITYSVC_API_KEY \
  --restart unless-stopped \
  ghcr.io/bopeng/ai-marketplace-monitor:latest

UNITYSVC_API_KEY needs a UnitySVC account and an API key you create there. In the default configuration, that one key covers any AI engine (OpenAI, Anthropic and more, as UnitySVC platform services or with your own provider keys saved in UnitySVC) and email and phone notifications; see AI Services and UnitySVC notification.

Then open http://localhost:8467 and sign in with your Facebook username and password, the values of FACEBOOK_USERNAME and FACEBOOK_PASSWORD. If Facebook asks for a check, click Open browser in the banner of the web UI and complete it there; searches start once you are logged in.

The Docker installation guide (source) covers the ways to run the image, from the container engine itself to NAS and home-server systems:

• Docker, the container engine: docker run, as above, starts the container from the command line.
• Docker Compose, Docker's tool for declarative configuration: the container is described in docker-compose.yml, with its settings in a .env file (both in docker-compose/), and docker compose up -d creates it the same way every time.
• Portainer, a web interface for managing Docker containers and Compose stacks: point its App Templates at a community template list that includes aimm, and deploy aimm from there.
• Synology and QNAP NAS run containers in their own apps, Container Manager and Container Station, so aimm runs on your NAS around the clock with the same Compose file.
• Unraid: add aimm's template, then create the container from it under Docker › Add Container.
• TrueNAS SCALE: add aimm as a custom app with Install via YAML and our configuration file, deploy/truenas/install-via-yaml.yaml.
• CasaOS and ZimaOS: import aimm's template with Custom Install.
• Cosmos: import aimm's template under ServApps.

The guide also covers running behind a reverse proxy, updates, and running aimm commands in the container.

💡 Example Usage

These are examples of configuration sections that aimm configure can create or update for you. Advanced users can still edit the TOML file directly.

Find GoPro cameras under $300:

[item.gopro]
search_phrases = 'Go Pro Hero'
keywords = "('Go Pro' OR gopro) AND (11 OR 12 OR 13)"
min_price = 100
max_price = 300

Search nationwide with shipping:

[item.rare_item]
search_phrases = 'vintage collectible'
search_region = 'usa'
delivery_method = 'shipping'
seller_locations = []

AI-powered filtering:

[ai.openai]
api_key = 'your_openai_key'

[item.camera]
description = '''High-quality DSLR camera in good condition.
Exclude listings with water damage or missing parts.'''
rating = 5  # Only notify for great deals (default: 4+)

Alerts on your phone and by email, plus a daily digest:

[user.me]
email = 'me@gmail.com'
notify_with = ['unitysvc', 'gmail']
# every morning at 8: a summary of everything aimm did in the last 24 hours,
# in full by email and as a short message on your phone
digest_at = '08:00'

[notification.unitysvc]
unitysvc_api_key = '${UNITYSVC_API_KEY}'

[notification.gmail]
smtp_password = '${GMAIL_APP_PASSWORD}'

📚 Documentation

For detailed information on setup and advanced features, see the comprehensive documentation:

• 📖 Full Documentation - Complete guide and reference
• 🚀 Quick Start Guide - Get up and running in 10 minutes
• 🔍 Features Overview - Complete feature list
• 📱 Usage Guide - Command-line options and tips
• 🔧 Configuration Guide - Notifications, AI prompts, multi-location search
• ⚙️ Configuration Reference - Complete configuration reference
• 🖥️ Web UI Guide - Built-in web interface for config editing and monitoring

Key Topics Covered in Documentation

Notification Setup:

• UnitySVC notification catalog with 100+ channels, plus Email (SMTP), PushBullet, PushOver, Telegram, and Ntfy
• Multi-user configurations
• HTML email templates

AI Integration:

• AI-assisted configuration editing with aimm configure
• UnitySVC access to almost arbitrary AI models, plus OpenAI, DeepSeek, Gemini, Anthropic, and Ollama setup
• Custom prompt configuration
• Rating thresholds and filtering

Advanced Search:

• Multi-city and region search
• Currency conversion
• Keyword filtering with Boolean logic
• Searching through a proxy

Configuration:

• TOML file structure
• Environment variables
• Multiple marketplace support
• Language/translation support

🤝 Contributing

Contributions are welcome! Here are some ways you can contribute:

• 🐛 Report bugs and issues
• 💡 Suggest new features
• 🔧 Submit pull requests
• 📚 Improve documentation
• 🏪 Add support for new marketplaces
• 🌍 Add support for new regions and languages
• 🤖 Add support for new AI providers
• 📱 Add new notification methods

Please read our Contributing Guidelines before submitting a Pull Request.

📜 License

This project is licensed under the Affero General Public License (AGPL). For the full terms and conditions, please refer to the official GNU AGPL v3.

💬 Support

We provide multiple ways to access support and contribute to AI Marketplace Monitor:

• 💬 Discord - Ask questions, share your searches, and hear about new releases (no GitHub account needed)
• 📖 Documentation - Comprehensive guides and instructions
• 🤝 Discussions - Community support and ideas
• 🐛 Issues - Bug reports and feature requests
• 💖 Become a sponsor - Support development
• 💰 Donate via PayPal - Alternative donation method

Important Note: Due to time constraints, priority support is provided to sponsors and donors. For general questions, please join us on Discord or use GitHub Discussions; report bugs as GitHub Issues.

🙏 Credits

• Some of the code was copied from facebook-marketplace-scraper.
• Region definitions were copied from facebook-marketplace-nationwide, which is released under an MIT license as of Jan 2025.
• This package was created with Cookiecutter and the cookiecutter-modern-pypackage project template.