How to Build a QQ Bot with Mirai and Python: Step‑by‑Step Guide

Prerequisites

Assume you have installed the required runtimes such as Java and Python.

Mirai Ecosystem

Mirai core consists of mirai-core and mirai-core-api. The API part is what developers interact with. mirai-console wraps the core and provides convenient interfaces.

Plugins are built for mirai-console; Java or Kotlin is normally required.

If you prefer other languages, use the mirai-api-http plugin, which exposes HTTP/WebSocket APIs.

Getting Started

Running mirai‑console with mirai‑console‑loader

Download mirai-console-loader (mcl) from its GitHub repository and extract it.

Open a command prompt, navigate to the mcl directory, and run mcl. Screenshots show successful startup.

If the launch fails due to a configuration error, edit the config file as shown in the image and retry.

Handling the slider captcha with mirai‑login‑solver‑selenium

After starting mcl, log in with login <account> <password>. The login will fail because the console cannot solve the slider captcha.

Install mirai-login-solver-selenium (requires Chrome). Add the plugin via:

mcl --update-package net.mamoe:mirai-login-solver-selenium --channel nightly --type plugin

Download the matching chromedriver manually, rename it to the expected filename (e.g., chromedriver-86.0.4240.198.exe), and replace it in the indicated directory.

Restart mcl and log in again; the browser window will appear for manual verification.

Extending language support with mirai‑api‑http

Download the mirai-api-http JAR and place it in the plugins folder.

Restart mcl and log in. If you encounter a signature verification error, replace Oracle JDK with OpenJDK.

Install OpenJDK, add its bin directory to the system PATH, and verify the environment variables.

Developing the bot in Python using graia‑application‑mirai

Configure mirai-api-http (see the sample setting.yml below):

# file: mcl-1.0.3/config/net.mamoe.mirai.api.http/setting.yml
authKey: graia-mirai-api-http-authkey
cacheSize: 4096
enableWebsocket: true
host: '0.0.0.0'
port: 8080

Restart mcl to apply the configuration.

Install the Python client library: pip install graia-application-mirai Create bot.py with the following code and run it:

from graia.broadcast import Broadcast
from graia.application import GraiaMiraiApplication, Session
from graia.application.message.chain import MessageChain
from graia.application.message.elements.internal import Plain
from graia.application.friend import Friend
import asyncio

loop = asyncio.get_event_loop()

bcc = Broadcast(loop=loop)
app = GraiaMiraiApplication(
    broadcast=bcc,
    connect_info=Session(
        host="http://localhost:8080",
        authKey="graia-mirai-api-http-authkey",
        account=5234120587,
        websocket=True
    )
)

@bcc.receiver("FriendMessage")
async def friend_message_listener(app: GraiaMiraiApplication, friend: Friend):
    await app.sendFriendMessage(friend, MessageChain.create([Plain("Hello, World!")]))

app.launch_blocking()

Send any message to your QQ bot; if it replies with "Hello, World!", the setup is successful.

Conclusion

The steps above constitute a basic tutorial for developing a QQ bot with Mirai. For more advanced features, refer to the official Mirai documentation.