A Discord bot for discovering, exploring and tracking projects on Modrinth.

Note

This bot is not associated with or endorsed by Modrinth.

🏁 Geting Started

Add the bot, then run /help to see all available commands.

Prefer to run your own instance? See 🚀 Self-hosting below.

✨ Commands

The /help command shows:

General

• /search · Search for projects on Modrinth
• /project · Look up a Modrinth project
• /version · Look up a version of a Modrinth project
• /random · Returns a random project from Modrinth
• /user · Look up a Modrinth user
• /organization · Look up a Modrinth organization
• /collection · Look up a Modrinth collection
• /identify · Identify a project file by uploading it

Tracking

• /tracking setup · Set the defaults used by everything this server tracks
• /tracking add · Start tracking a Modrinth project
• /tracking remove · Stop tracking a project
• /tracking author add · Start tracking a Modrinth user or organization
• /tracking author remove · Stop tracking an author
• /tracking manage · Manage projects and authors tracked in this server
• /tracking pause · Pause tracking notifications without removing tracked projects and authors
• /tracking resume · Resume tracking notifications for this server
• /tracking disable · Disable tracking and remove all tracked projects and authors
• /tracking help · Explain how tracking, overrides, and authors work

Account

• /account link · Link your Modrinth account to your Discord account
• /account unlink · Unlink your Modrinth account
• /account status · Show which Modrinth account is linked

Roles

• /roles add · Give a role to members whose linked Modrinth account meets optional conditions: project or organization team, downloads, projects, followers, project type, badge, account age
• /roles remove · Stop giving out a role
• /roles manage · Manage this server's roles
• /roles list · Show this server's roles and what they require
• /roles get · Get the roles your Modrinth account qualifies for
• /roles help · Explain how roles, conditions, and syncing work

Donate

• /donate info · Show Ko-fi donation info and perks
• /donate list · Show public donations
• /donate activate · Activate donator perks using your Ko-fi account
• /donate status · Check the donator status of this server

Miscellaneous

• /options · Manage server bot options
• /statistics · Show Modrinth and bot statistics
• /vote · Vote for the bot on top.gg
• /ping · Replies with Pong!

🚀 Self-hosting

The recommended deployment is Docker Compose with the published container image on GHCR.

Prerequisites: Docker and an application on Discord.

1. Create docker-compose.yml

services:
  bot:
    image: ghcr.io/creeperkatze/modrinth-scout:latest
    restart: unless-stopped
    env_file: .env
    depends_on:
      - mongodb
    networks:
      - backend

  mongodb:
    image: mongo:8
    restart: unless-stopped
    volumes:
      - mongodb-data:/data/db
    networks:
      - backend

volumes:
  mongodb-data:

networks:
  backend:
    driver: bridge

2. Create .env

DISCORD_TOKEN=your_bot_token
DISCORD_CLIENT_ID=your_application_id

MONGODB_URI=mongodb://mongodb:27017/modrinth_scout

3. Start

docker compose up -d

Slash commands are deployed automatically during startup.

👨‍💻 Development

pnpm dev

Runs the bot with tsx in watch mode, no build step needed. Deploy commands to a dev guild for instant updates:

DISCORD_GUILD_ID=your_guild_id

🤝 Contributing

Contributions are always welcome!

Please ensure you run pnpm lint:fix before opening a pull request.

📜 License

AGPL-3.0