MAID Bot ♡ v1.0

Movie Archive & Interactive Database

A cute Discord bot for managing your movie watchlist! MAID is an eager-to-serve assistant who helps you track movies for movie night, create polls, pick random films, schedule movie nights, and more~ ✨

Features

🎬 Add movies to your watchlist

📋 List unwatched and watched movies

✅ Mark movies as watched

🗑️ Remove movies from the list

🎲 Random pick for movie night

🗳️ Vote on 5 random movies with polls

📊 Statistics - see who added the most!

🎥 Movie info from TMDB

📅 Plan movie nights with reminders

🏠 Per-server movie lists

Slash Commands

Movie Management

Command	Description
`/add <title>`	Add a movie to the watchlist
`/list`	Show all unwatched movies
`/watched`	Show all watched movies
`/remove <title>`	Remove a movie from the list
`/mark <title>`	Mark a movie as watched
`/random`	Pick a random unwatched movie
`/vote`	Create a poll with 5 random movies
`/stats`	Show database statistics
`/info <title>`	Get movie details from TMDB

Scheduling

Command	Description
`/schedule <date> <time> [movie]`	Schedule a movie night (e.g., `/schedule 02/15 20:00`)
`/upcoming`	Show all scheduled movie nights
`/cancel <id>`	Cancel a scheduled movie night

Setup

Prerequisites

Python 3.10 or higher
A Discord bot token (Create one here)
(Optional) TMDB API key for /info command (Get one here)

Local Development

Clone or download the bot files

Create virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or: .\venv\Scripts\activate  # Windows
pip install -r requirements.txt

Configure the bot

cp .env.example .env
# Edit .env and add your tokens

Run the bot

python bot.py

Environment Variables

DISCORD_TOKEN=your_discord_bot_token_here
TMDB_API_KEY=your_tmdb_api_key_here  # Optional

Discord Bot Setup

Go to the Discord Developer Portal

Create a new application

Go to the "Bot" section and create a bot

Copy the bot token and add it to your .env file

Under "Privileged Gateway Intents", enable "Message Content Intent"

Go to "OAuth2" → "URL Generator"

Select scopes: bot, applications.commands

Select permissions: Send Messages, Embed Links, Add Reactions, Use Slash Commands, Mention Everyone

Copy the generated URL and invite the bot to your server

Raspberry Pi Deployment

Initial Setup

Install Python and venv

sudo apt update
sudo apt install python3 python3-venv python3-pip

Create bot directory and copy files

mkdir -p ~/maid-bot
cd ~/maid-bot
# Copy all bot files here

Create virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure the bot

cp .env.example .env
nano .env  # Add your DISCORD_TOKEN and TMDB_API_KEY

Test the bot (optional)

source venv/bin/activate
python bot.py
# Press Ctrl+C to stop

Systemd Service Setup

Edit the service file to match your username and paths

nano maid.service
# Update User, WorkingDirectory, ExecStart, and EnvironmentFile

Copy the service file

sudo cp maid.service /etc/systemd/system/

Reload systemd and enable the service

sudo systemctl daemon-reload
sudo systemctl enable maid

Start the bot

sudo systemctl start maid

Check status

sudo systemctl status maid

Useful Commands

Command	Description
`sudo systemctl start maid`	Start the bot
`sudo systemctl stop maid`	Stop the bot
`sudo systemctl restart maid`	Restart the bot
`sudo systemctl status maid`	Check bot status
`journalctl -u maid -f`	View live logs
`journalctl -u maid --since "1 hour ago"`	View recent logs

Updating the Bot

cd ~/maid-bot
source venv/bin/activate
# Pull changes or copy new files
pip install -r requirements.txt  # If dependencies changed
sudo systemctl restart maid

Project Structure

maid-bot/ ├── bot.py # Main entry point ├── database.py # SQLite database operations ├── tmdb.py # TMDB API client ├── cogs/ │ ├── __init__.py │ └── movies.py # Slash commands ├── .env # Environment variables ├── .env.example # Example environment file ├── requirements.txt # Python dependencies ├── maid.service # Systemd service file ├── movies.db # SQLite database (auto-created) └── README.md # Documentation

Database

MAID uses SQLite to store movies and schedules. The database file (movies.db) is created automatically.

Movies Table

Field	Description
`id`	Auto-incrementing primary key
`guild_id`	Discord server ID (per-server lists)
`title`	Movie title (unique per server)
`added_by`	Discord username who added the movie
`added_date`	Timestamp when added
`watched`	Boolean flag (0 = unwatched, 1 = watched)

Schedules Table

Field	Description
`id`	Schedule ID
`guild_id`	Discord server ID
`channel_id`	Channel for notifications
`movie_title`	Optional movie title
`scheduled_time`	When the movie night starts
`reminder_sent`	Whether 30-min reminder was sent
`created_by`	Who created the schedule

Troubleshooting

Bot doesn't respond to slash commands Make sure you invited the bot with applications.commands scope. Wait a few minutes for Discord to sync commands globally. Try restarting the bot.

"DISCORD_TOKEN not found" error Make sure you created the .env file and that DISCORD_TOKEN is set correctly.

/info command not working Add TMDB_API_KEY to your .env file. Get a free API key from TMDB.

Service won't start Check logs with journalctl -u maid -f. Verify paths in the service file match your installation. Make sure venv is set up correctly.

Database errors after update Delete old database with rm movies.db and restart bot to create a fresh database.