ai-marketplace-monitor 0.10.4

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

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.

What's New

• 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.
• Anthropic/Claude AI Backend: Use Claude models (e.g. claude-sonnet-5-5) to evaluate listings alongside OpenAI, DeepSeek, Gemini, and Ollama. See AI Services for configuration.
• Configurable Rate Limiting: Rate limiting framework for all notification types with per-instance and global limits. Telegram notifications use optimized defaults automatically.

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

🖥️ Web UI

• Built-in config editor with TOML syntax highlighting
• Live log streaming and filtering
• 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 configure

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

Run the Monitor

aimm

The program will open a browser, search Facebook Marketplace, and notify you of matching items. 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.

Run with Docker

A prebuilt Linux image is published to GitHub Container Registry. It bundles Python, Playwright Chromium, a virtual display (Xvfb), and an embedded noVNC client so you can solve Facebook CAPTCHAs / interactive logins from the web UI — useful on macOS, headless servers, or NAS boxes.

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

Then open http://localhost:8467. When Facebook needs an interactive login or CAPTCHA, click the Browser button in the header to view and control the in-container Chromium.

Mounting ~/.ai-marketplace-monitor shares your existing config, cache, and logs between the host install and the container — so you can switch back and forth freely. Update with docker pull ghcr.io/bopeng/ai-marketplace-monitor:latest && docker restart aimm.

To build the image yourself instead of pulling: docker build -t aimm . from a checkout of this repo.

💡 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 = 4  # Only notify for 4+ star AI ratings

📚 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
• Proxy/anonymous searching

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:

• 📖 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 use the GitHub Discussions or 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.