AI Chatbot

AI Chatbot is an in-game AI chat helper for your server. Players greet it or ask it questions in chat, and it answers using your own server rules, lore, and info — not generic made-up answers. It can optionally hand out items too, with limits you control.

Nothing about it is pre-loaded with any particular server's content — every default ships as an empty-ish template meant to be replaced. You write what it knows; it just answers in your voice.

Quick start

Install. Drop the jar in plugins/ (Paper) or mods/ (Fabric/Forge/NeoForge) and start the server once. That generates config.yml, server-info.md, and a kb/ folder.
Get a free Groq API key (genuine permanent free tier, no credit card):
1. Sign up at console.groq.com (Google/GitHub/email).
2. Go to console.groq.com/keys, click Create API Key, name it anything (e.g. mc-server), and copy the key — Groq only shows it once.
3. Open config.yml (generated in step 1) and paste the key in under ai.apiKey. The exact path depends on your platform:
  
  Platform config.yml path
  
  Paper plugins/mcAIChatbot/config.yml
  
  Fabric / Forge / NeoForge config/mcAIChatbot/config.yml
```
ai:
  provider: "openai-compatible" # already the default — Groq speaks this wire format
  apiKey: "gsk_...paste your key here..."
  baseUrl: "https://api.groq.com/openai/v1"
  models:
    - "groq/compound"
    - "openai/gpt-oss-120b"
    - "openai/gpt-oss-20b"
```
  (Model lineup changes over time — check console.groq.com/docs/models for the current list if these stop working. Skip anything named prompt-guard — that's an input-safety classifier, not a chat model.)
Keep this a free-tier account with no payment method attached — see "Groq key" below for why that matters, and what to do if a key ever leaks.
Fill in server-info.md (short bullet points: server name, rules, key commands) and drop your own .md files into kb/ for anything else players might ask about.
Save, then reload. Run /mcaichatbot reload in-game (or restart the server) — you're live.

Platform	`config.yml` path
Paper	`plugins/mcAIChatbot/config.yml`
Fabric / Forge / NeoForge	`config/mcAIChatbot/config.yml`

Full configuration reference, every option explained: see "Setup guide" below.

Groq key

Groq is the default AI provider this project ships pointed at, and it has a genuine permanent free tier — no credit card required to sign up or to generate a key. For the actual signup and setup steps, see "Quick start" above — this section covers the reasoning and what to do if the key leaks.

Free tier

Your API key lives in a plaintext config file (config.yml) on whatever machine runs your mc server. If that hosting is ever compromised, shared with other tenants, or accessible to anyone besides you — which is common on cheap/shared game hosting — that key can leak.

A free-tier key with no payment method attached is low-stakes if it leaks: worst case, someone burns your free rate limit and you rotate the key. No bill.
A paid key or one with a card attached is a real financial risk if it leaks: someone could run up usage charges before you notice.

So: create a free Groq account, don't add a payment method to it, and use only that key here.

If leaked

Rotate it immediately at console.groq.com/keys — delete the old key and create a new one. Don't just remove it from wherever it leaked; assume it's already been seen.

Never

Never commit config.yml with a real key in it to a public repo.
Never hand out a jar or config with your key baked in — every server install should generate and use its own key.
Never attach a payment method to the account this key belongs to.

Free key

This plugin/mod needs an API key from an AI provider to work (Groq by default — a real permanent free tier, no credit card). Only ever use a free-tier account with no payment method attached. The key lives in a plaintext config file on whatever machine hosts your server, and hosting (especially cheap/shared hosting) can be compromised or have other people with filesystem access. A leaked free-tier key costs you nothing worse than rate-limiting on a $0 account; a leaked paid key can run up a real bill. See "Quick start" above for the 2-minute signup steps, "Groq key" above for the full reasoning, and "Content disclosures" right below this for what data gets sent where.

Content disclosures

This project connects to a third-party AI API. To generate chat replies, this plugin/mod sends the text of player questions (and short server context you write yourself — no personal player data) to an AI provider's API. By default that provider is Groq; the config also supports OpenAI-compatible endpoints, OpenRouter, and Anthropic if you choose to switch. You must supply your own API key from that provider — none is bundled, and the plugin/mod does nothing until you add one.

Every AI provider option documented for this project (Groq, OpenRouter's :free models, local Ollama) has a genuine free tier that needs no card — see the "Groq key" section above for the default path, and don't attach billing to that account.

Optional Discord relay. If you turn on the optional Discord webhook relay, chat lines get posted to a Discord channel via a webhook URL you provide. This is off by default and, like the AI key, is a credential you supply and control — treat a webhook URL with the same care (don't share it, rotate it if it leaks).

No player data leaves your server other than the chat text needed to generate a reply, sent directly to the AI provider you configured.

Features

Answers questions in chat — type !ai <question> (prefix configurable), get a reply built from your server-info.md and kb/ knowledge-base files.
Join greetings — welcomes players when they log in.
Personality modes — friendly or trashtalk, your choice.
Configurable chat styling — bot name and message color/bold, set from chat or config.yml.
Per-player and server-wide conversation memory, so it remembers context across messages.
Optional item giving — the AI can hand out items on request, capped by daily-per-player limits, stack-size limits, and separate equipment limits. Off by default; turn it on with one config flag if you want it.
Batched AI calls — questions from multiple players in the same short window go out as one AI request, not one per player, so it's cheap to run even on a busy server.
Model fallback/rotation across your configured models, so a single overloaded/rate-limited model doesn't take the whole thing down.
Optional Discord relay — mirror join greetings and !ai replies into a Discord channel via a plain incoming webhook. Off by default; no bridge plugin required.
In-game admin commands — view and change most settings from chat (/mcaichatbot config, get, set, models) with no restart needed, or just reload after a manual file edit.
Crash-safe state persistence — cooldowns and conversation memory survive restarts.

Supported platforms

Platform	mc versions
Paper	one jar, forward-compatible from 1.21.11 through the 26.x line
Fabric	1.21.11, 26.1, 26.2
Forge	1.21.11, 26.1, 26.2
NeoForge	1.21.11, 26.1, 26.2

Every platform uses the exact same config.yml shape and keys — copy one platform's config to another and it just works.

Setup guide

Everything you need to install, configure, and run mc AI Chatbot on any of the four supported platforms.

Install

Platform	Where the jar goes	Files generated on first start
Paper	`plugins/`	`plugins/mcAIChatbot/config.yml`, `server-info.md`, `kb/`
Fabric	`mods/`	`config/mcaichatbot/config.yml`, `server-info.md`, `kb/`
Forge	`mods/`	`config/mcaichatbot/config.yml`, `server-info.md`, `kb/`
NeoForge	`mods/`	`config/mcaichatbot/config.yml`, `server-info.md`, `kb/`

Pick the jar matching your loader and mc version (1.21.11, 26.1, or 26.2 — Paper ships one jar that covers all of them). Start the server once to generate the files above, then it won't answer anything useful until you fill in two of them: an API key, and your own server info.

API key

Use a free-tier account with no payment method attached — not a paid one. This project's config keeps apiKey as plain text in config.yml on your server's own filesystem; a free key only risks hitting a rate limit if it ever leaks, a paid one risks a real bill. Every provider option below has a genuine free tier that needs no card.

The shipped default is Groq — see "Quick start" above for the step-by-step signup, or "Groq key" above for the reasoning behind the free-tier requirement.

Set these four fields under ai: in config.yml:

ai:
  provider: "openai-compatible" # shipped default — see the Groq key guide below
  apiKey: "..." # your own free-tier key — never share one across installs
  baseUrl: "https://api.groq.com/openai/v1"
  models:
    - "groq/compound"
    - "openai/gpt-oss-120b"
    - "openai/gpt-oss-20b"

(The config also supports OpenRouter and Anthropic as alternate providers if you'd rather use those — both have free options too — but this guide only covers the Groq path, since it's the default and needs no extra setup beyond the key itself.)

apiKey is the one field that always needs a direct file edit — see "Admin commands" below for every other setting. After changing this, run /mcaichatbot reload or restart the server. Pending questions, item-give cooldowns, and conversation history all survive a reload — only config.yml/server-info.md/kb/ get re-read. Needs op-equivalent permission (Paper: mcaichatbot.reload, default op, alias /maic; Fabric/Forge/NeoForge: vanilla permission level 4, same as /op).

Server info

Nothing ships pre-loaded with any particular server's content — every default is a template meant to be replaced.

server-info.md — short, factual bullet points: server name, rules, gamemode, key commands/plugins, links. This gets pasted into every prompt, so keep it tight.
kb/ — a folder, not a single file. Drop in as many .md files as you want for anything server-info.md doesn't have room for (game systems, lore, item lists, event rules). Ships with one example file showing the format — delete the example, write your own. Files are read in filename order (01-..., 02-...) if order matters. Give things clear headings/bold text — that's what gets matched against a player's question.

Both are re-read live on every question — no reload needed for these two.

Item giving

itemGiving:
  enabled: false # master switch (shipped default) — true lets the bot give items when asked
  maxPerDay: 10 # per player, rolling 24h window
  maxQuantity: 64 # ordinary stackable items
  maxEquipmentQuantity: 1 # weapons/armor/tools/etc (vanilla max stack size 1 anyway)

Turning enabled: false doesn't just stop gives from happening — the AI is told never to offer one, and if it ignores that, the plugin overrides its reply with a plain "item giving is off here" message instead of letting a promised-but-undelivered item slip through.

Other tunables

Key	What it does
`botName`	the name shown in chat before every bot message, default `"mcAi"`
`chatStyle`	name/message color and bold, e.g. `chatStyle.nameColor: "blue"`
`personality`	`"friendly"` or `"trashtalk"` — the bot's tone
`askPrefix`	the chat prefix players type, default `"!ai"`
`batchWindowMs`	how often queued questions go out as one AI call (default 10s)
`maxAsksPerWindow`	total questions accepted per window, across all players
`askCooldownSeconds`	per-player pacing independent of `batchWindowMs`
`maxAskSubparts`	how many distinct requests one message can resolve at once
`broadcastReplies`	`true` = bot replies go to server-wide chat; `false` = console log only

Every key in this table (and item-giving's, above) can also be changed from chat — see "Admin commands" below.

Discord relay

Every bot chat line (join greetings, !ai replies) can be relayed into a Discord channel via an incoming webhook — no bridge plugin needed, off by default:

In Discord: target channel → Settings → Integrations → Webhooks → New Webhook → Copy Webhook URL.

In config.yml:

discord:
  webhookUrl: "https://discord.com/api/webhooks/..."
  username: "" # optional — overrides the name Discord shows; blank uses the webhook's own

/mcaichatbot reload or restart.

Leave webhookUrl blank (the default) to keep this off. A relay failure (bad URL, Discord down, rate-limited) is logged and dropped; it never affects the in-game reply that triggered it.

Admin commands

Most of config.yml can be changed from in-game chat instead of hand-editing the file:

/mcaichatbot config — lists every editable key and its current value.
/mcaichatbot get <key> / /mcaichatbot set <key> <value> — view or change one, e.g. /mcaichatbot set chatStyle.nameColor red or /mcaichatbot set personality trashtalk.
/mcaichatbot models list|add|remove <id> — manage the ai.models list.
/mcaichatbot reload — re-read config.yml/server-info.md/kb/ after a manual file edit.

Every set/add/remove above reloads automatically — no separate /mcaichatbot reload needed. ai.apiKey is the one exception: it's never viewable or settable via command (a secret shouldn't be echoed into chat or server logs), so that field alone still needs a direct edit to config.yml. Same permission as reload (see "API key" above).

Security notes

Use a free-tier API key and Discord webhook — see "Free key" above for why.
Never commit config.yml with a real key in it anywhere, and never hand out a jar/config with your key baked in — every install needs its own.
If a key ever ends up somewhere it shouldn't (pasted in chat, committed to a public repo, etc.), rotate it at the provider's console immediately — don't just remove it from wherever it leaked.

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Links

Tags

Creators

Details