explaingit

mamoe/mirai

Analysis updated 2026-06-24

14,848KotlinAudience · developerComplexity · 3/5LicenseSetup · moderate

TLDR

mirai is a Kotlin library that implements the QQ Android client protocol so you can build cross-platform QQ chat bots that handle messages, groups, and friends.

Mindmap

mindmap
  root((mirai))
    Inputs
      QQ login
      Group events
      Friend events
    Outputs
      Text and emoji
      Images stickers
      Group actions
    Use Cases
      Build a QQ chat bot
      Automate group moderation
      Bridge QQ to other apps
    Tech Stack
      Kotlin
      JVM
      QQ Protocol
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Build a QQ bot that auto-replies to group mentions with text, images, and stickers.

USE CASE 2

Automate moderation of a QQ group with mutes, kicks, join-request handling, and announcements.

USE CASE 3

Forward messages between a QQ group and another chat platform like Discord or Telegram.

USE CASE 4

Send scheduled XML or JSON rich messages to a friends list as a hobby notification bot.

What is it built with?

KotlinJVM

How does it compare?

mamoe/miraiktorio/ktoramir1376/ab-download-manager
Stars14,84814,40215,443
LanguageKotlinKotlinKotlin
Setup difficultymoderatemoderateeasy
Complexity3/53/52/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

AGPLv3 obligation is strict, commercial use is also discouraged by the maintainers and QQ login can trigger account risk checks.

AGPLv3 licensed: any project that uses mirai, even over a network bridge, must also be open source under AGPLv3.

In plain English

mirai is an open source library, written mainly in Kotlin, for building bots that talk to QQ, the very popular Chinese chat service. The README describes it as a high-efficiency bot library that runs across platforms and implements the QQ Android client protocol, which means a program using mirai can sign in as a QQ user and read or send messages the way the mobile app does. The project name is a reference to characters from Japanese anime and music, and the logo art was contributed by a community artist. The README opens with a strong statement of intent. The project is free, fully open source, maintained by the community, and meant for learning and entertainment only. The authors say it must not be used for illegal purposes, and they also say it should not be used commercially. The license is AGPLv3, and the README warns that any project that talks to mirai, even through an HTTP API or cross-process bridge, must also be open source under AGPLv3. A collapsible section lists what the library can do. On the messaging side it supports text, native and shop emoji, the nudge action, images and custom stickers, rich XML and JSON messages, long messages of up to 5000 characters with 50 images, quote replies, forwarded message bundles, message recall, mentions of one or all group members, voice, and flash photos. For group management it handles member lists, permissions, mutes, announcements, group settings, and join requests. For friends it handles the full friend list and friend requests. The README also lists what mirai will not implement: anything money related, sensitive actions like sending friend requests on its own, and account security operations like extracting login tokens.

Copy-paste prompts

Prompt 1
Build a minimal mirai Kotlin bot that logs into QQ, joins a group, and replies hi when anyone mentions it.
Prompt 2
Add image and custom sticker support to a mirai bot so it can post a meme when a keyword fires.
Prompt 3
Wire a mirai bot to a SQLite database that tracks group join requests and auto-approves on a whitelist.
Prompt 4
Bridge a QQ group and a Discord channel by combining mirai with discord.kt and forwarding text both ways.
Prompt 5
Add quote replies, mentions, and message recall handling to a mirai group-moderation bot.

Frequently asked questions

What is mirai?

mirai is a Kotlin library that implements the QQ Android client protocol so you can build cross-platform QQ chat bots that handle messages, groups, and friends.

What language is mirai written in?

Mainly Kotlin. The stack also includes Kotlin, JVM.

What license does mirai use?

AGPLv3 licensed: any project that uses mirai, even over a network bridge, must also be open source under AGPLv3.

How hard is mirai to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is mirai for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.