![\"ServerChan](\"https:\/\/raw.githubusercontent.com\/himekifee\/ServerChan\/main\/common\/src\/main\/resources\/assets\/serverchan\/icon.png\"){kind=icon}
\n<\/p>\n# ServerChan<\/p>\n
\n
\n
\n
\n
\n<\/p>\n
\n \n<\/p>\n
ServerChan is a friendly, AI-powered helper for Minecraft servers. It listens to chat, reacts to in-game events, and can even carry out commands when you give it permission. Whether you run a cozy SMP or a busy public server, ServerChan keeps conversations lively without spamming players.<\/p>\n
## Features<\/p>\n
– **AI Chat Integration** – Uses OpenAI-compatible APIs (OpenAI, Azure, local LLMs, etc.) to power intelligent conversations
\n– **Smart Response System** – Optional intention checker determines when the AI should respond, avoiding spam
\n– **Game Event Awareness** – Reacts to player joins\/leaves, deaths, and other server events
\n– **Command Execution** – AI can execute Minecraft commands via function calling (with permission controls)
\n– **Multi-Loader Support** – Works on Fabric, Forge, NeoForge, and Spigot\/Paper
\n– **Multi-Version Support** – Compatible with Minecraft 1.12 – 1.21
\n– **Fully Configurable** – Customize prompts, models, response behavior, and more
\n– **Internationalization** – Built-in i18n support (English, Chinese, Japanese)<\/p>\n
## Demo<\/p>\n
\n ![\"ServerChan](\"https:\/\/raw.githubusercontent.com\/himekifee\/ServerChan\/main\/example\/welcome.png\")
\n<\/p>\n
\n ![\"ServerChan](\"https:\/\/raw.githubusercontent.com\/himekifee\/ServerChan\/main\/example\/command.png\")
\n<\/p>\n
## Loader Compatibility Matrix<\/p>\n
| Version | Java | Fabric | Forge | NeoForge | Spigot\/Paper |
\n|———|——|——–|——-|———-|————–|
\n| 1.12.x | 8 | \u2014 | \u274c | \u2014 | \u2705 |
\n| 1.13.x | 8 | \u2014 | \u274c | \u2014 | \u2705 |
\n| 1.14.x | 8 | \u2705 | \u274c | \u2014 | \u2705 |
\n| 1.15.x | 8 | \u2705 | \u274c | \u2014 | \u2705 |
\n| 1.16.x | 8 | \u2705 | \u2705 | \u2014 | \u2705 |
\n| 1.17.x | 16 | \u2705 | \u2705 | \u2014 | \u2705 |
\n| 1.18.x | 17 | \u2705 | \u2705 | \u2014 | \u2705 |
\n| 1.19.x | 17 | \u2705 | \u2705 | \u2014 | \u2705 |
\n| 1.20.x | 21 | \u2705 | \u2705 | \u2705 | \u2705 |
\n| 1.21.x | 21 | \u2705 | \u2705 | \u2705 | \u2705 |<\/p>\n
`\u2014` means the loader didn’t exist for that version (Fabric starts at 1.14, NeoForge at 1.20).<\/p>\n
## Installation<\/p>\n
You’re just five steps away from a chatty server buddy:<\/p>\n
1. Grab the jar that matches your loader from Modrinth or CurseForge
\n2. Drop it into the `mods\/` folder (or `plugins\/` for Spigot\/Paper)
\n3. Launch the server once so the config file appears
\n4. Add your API key plus any tweaks you want (see [Configuration](#configuration))
\n5. Restart or `\/reload` and start chatting<\/p>\n
## Configuration<\/p>\n
The config file lives at:
\n– **Fabric\/Forge\/NeoForge**: `config\/serverchan.yaml`
\n– **Spigot**: `plugins\/ServerChan\/config.yml`<\/p>\n
### Required Settings<\/p>\n
| Option | Description |
\n|——–|————-|
\n| `openaiApiKey` | Your OpenAI API key (or compatible provider) |
\n| `openaiBaseUrl` | API base URL (default: `https:\/\/api.openai.com\/v1`) **Important: Must include `\/v1` path** |<\/p>\n
### Optional Settings<\/p>\n
| Option | Default | Description |
\n|——–|———|————-|
\n| `model` | `gpt-5.1` | Model to use for responses |
\n| `temperature` | `1.0` | Response randomness (0.0 – 2.0) |
\n| `contextSize` | `20` | Number of messages to keep in context |
\n| `botColor` | `b` | Minecraft color code for bot chat |
\n| `timeZone` | `UTC` | Timezone for message timestamps |
\n| `locale` | `en` | Language for bot messages |<\/p>\n
### Intention Checker Settings<\/p>\n
The intention checker uses a smaller\/faster model to decide if the AI should respond.<\/p>\n
| Option | Default | Description |
\n|——–|———|————-|
\n| `useIntentionChecker` | `true` | Enable smart response filtering |
\n| `intentionCheckerModel` | `gpt-4o-mini` | Model for intention checking (personal rec: `qwen3-235b-a22b-2507` via Cerebras) |
\n| `responseProbabilityThreshold` | `0.5` | Minimum probability to trigger response |
\n| `useFastPathIntentionChecker` | `false` | Start response generation early |
\n| `intentionCheckerApiKey` | (empty) | Separate API key (uses main key if empty) |
\n| `intentionCheckerBaseUrl` | (empty) | Separate base URL (uses main URL if empty). **Must include `\/v1` path if set** |<\/p>\n
### Event Settings<\/p>\n
| Option | Default | Description |
\n|——–|———|————-|
\n| `enableGameEvents` | `true` | React to game events |
\n| `enableJoinLeaveEvents` | `true` | React to player join\/leave |
\n| `enableDeathEvents` | `true` | React to player deaths |<\/p>\n
### Permission Settings<\/p>\n
| Option | Default | Description |
\n|——–|———|————-|
\n| `inheritCmdSourcePermission` | `true` | AI inherits triggering player’s permissions for commands |<\/p>\n
### Custom Prompts<\/p>\n
You can customize the system prompts to match the vibe of your server:
\n– `intentionCheckingSystemMessage` – Controls when AI decides to respond
\n– `responseGenerationSystemMessage` – Controls AI personality and behavior<\/p>\n
### Example Prompts<\/p>\n
Sample prompt files live in the `example\/` folder to help you get started. For instance, `example\/OnlyMyRedstone-system-prompt.txt` captures the full response-generation setup used on the OnlyMyRedstone community server, and `example\/OnlyMyRedstone-intention-checking.txt` shows how that server throttles responses through intention checking. Feel free to duplicate and adapt these files for your own servers \u2014 they’re meant to be remixed.<\/p>\n
## Commands<\/p>\n
All commands require operator permissions (level 4).<\/p>\n
| Command | Description |
\n|———|————-|
\n| `\/serverchan reload` | Reload configuration |
\n| `\/serverchan reset` | Clear message context\/memory |
\n| `\/serverchan kill` | Reset the OpenAI client connection |
\n| `\/serverchan disable` | Pause ServerChan responses (no messages processed) |
\n| `\/serverchan enable` | Resume ServerChan responses |<\/p>\n
## How It Works<\/p>\n
1. **Player sends a message** in chat
\n2. **Intention Checker** (if enabled) evaluates if a response is appropriate
\n3. If response is needed, the **main model generates a reply**
\n4. The AI can optionally **execute commands** via function calling
\n5. Response is **broadcast to all players**<\/p>\n
The AI maintains conversation context and can reference previous messages within the configured context size.<\/p>\n
## Requirements<\/p>\n
– Minecraft Server 1.12 – 1.21 (see [compatibility matrix](#loader-compatibility-matrix))
\n– One of: Fabric, Forge, NeoForge, or Spigot\/Paper (availability varies by version)
\n– OpenAI API key (or compatible provider like Azure OpenAI, Ollama, etc.)<\/p>\n
## Building from Source<\/p>\n
“`bash
\n# Clone the repository
\ngit clone https:\/\/github.com\/himekifee\/ServerChan.git
\ncd ServerChan<\/p>\n
# Build for a specific Minecraft version
\n.\/gradlew build -PmcVer=1.21<\/p>\n
# Build merged jar (all loaders in one)
\n.\/gradlew build mergeJars -PmcVer=1.21
\n“`<\/p>\n
Built jars will be in `build\/libs\/` (or `build\/forgix\/` for merged jars).<\/p>\n
### Development Testing<\/p>\n
For local development, a test script is provided that builds the mod and spins up actual Minecraft servers to verify it loads correctly:<\/p>\n
“`bash
\n# Build and test on all platforms (requires Docker)
\n.\/dev-test.sh 1.21<\/p>\n
# Build only, skip server tests
\n.\/dev-test.sh –build-only 1.21<\/p>\n
# Test specific platform only
\n.\/dev-test.sh –fabric 1.21
\n.\/dev-test.sh –forge 1.21
\n.\/dev-test.sh –neoforge 1.21
\n.\/dev-test.sh –paper 1.21
\n“`<\/p>\n
The script requires Docker to run the server tests.<\/p>\n
## Contributing<\/p>\n
Contributions are welcome! Please feel free to submit issues and pull requests; we love hearing how you’re using ServerChan.<\/p>\n
1. Fork the repository
\n2. Create a feature branch (`git checkout -b feature\/amazing-feature`)
\n3. Commit your changes (`git commit -m ‘Add amazing feature’`)
\n4. Push to the branch (`git push origin feature\/amazing-feature`)
\n5. Open a Pull Request<\/p>\n
## Discord<\/p>\n
Join our Discord server to chat with the community, get help, or share your ServerChan setup!<\/p>\n
## License<\/p>\n
This project is licensed under the GNU General Public License v3.0 – see the [LICENSE](LICENSE) file for details.<\/p>\n
## Acknowledgments<\/p>\n
– Built on Universal Mod Template by thebuildcraft
\n– Uses ConfigLib for YAML configuration
\n– Uses Architectury Loom, Forgix, and Manifold<\/p>\n
## Cerebras<\/p>\n
Not sponsored by Cerebras, but I use their inference API for CI testing and my own server’s intention checker model \u2014 it’s blazingly fast! With a context of 20 messages, intention checking finishes within ~1 second, and full responses come back in about 2-5 seconds. That’s basically instant compared to other LLM providers that often need 20+ seconds to reply, making Cerebras a perfect fit for real-time chat applications like this. If anyone from Cerebras is interested in sponsoring API credits or any other form of support, feel free to open an issue \ud83d\ude0a<\/p>\n","protected":false},"excerpt":{"rendered":"
Bring AI to your Minecraft server – an intelligent chatbot that interacts with players and responds to in-game events<\/p>\n","protected":false},"featured_media":137533,"template":"","meta":{"_minecraft_slug":"serverchan","_minecraft_project_id":"frZpQL6O","_minecraft_author":"himekifee","_minecraft_license":"GPL-3.0-only","_minecraft_downloads":934,"_minecraft_follows":9,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"serverchan.zip","_minecraft_size_bytes":1136434463,"_minecraft_version_count":30,"_minecraft_updated_at":"2026-05-16T08:50:37.230275Z","_minecraft_date_created":"2025-12-13T06:45:55.317087Z","_minecraft_date_modified":"2025-12-16T11:19:55.786975Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/serverchan","_minecraft_icon_attachment_id":137533,"_minecraft_imported_at":"2026-06-08T03:08:39+00:00","_minecraft_import_hash":"f6ea17c0844ea96c6361ebcf0ebe08d7","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,97,104,158,867,129,92],"mod_loader":[99,106,160,134],"minecraft_version":[379,382,385,438,446,449,110,111,112,113,114,115,116,117,118,119,120,46,47,48,49,50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,73,74,38,78,79,80,81,82],"class_list":["post-137532","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-fabric","mod_category-forge","mod_category-neoforge","mod_category-social","mod_category-spigot","mod_category-utility","mod_loader-fabric","mod_loader-forge","mod_loader-neoforge","mod_loader-spigot","minecraft_version-1-12","minecraft_version-1-12-1","minecraft_version-1-12-2","minecraft_version-1-13","minecraft_version-1-13-1","minecraft_version-1-13-2","minecraft_version-1-14","minecraft_version-1-14-1","minecraft_version-1-14-2","minecraft_version-1-14-3","minecraft_version-1-14-4","minecraft_version-1-15","minecraft_version-1-15-1","minecraft_version-1-15-2","minecraft_version-1-16","minecraft_version-1-16-1","minecraft_version-1-16-2","minecraft_version-1-16-3","minecraft_version-1-16-4","minecraft_version-1-16-5","minecraft_version-1-17","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n