PaperChat - AI-Powered Minecraft Plugin
PaperChat is a Minecraft server plugin that integrates AI language models directly into Minecraft. It allows players to send messages to AI assistants and get answers quickly, creating natural conversation experiences powered by Google Gemini and OpenAI models, with the ability to add your own!
Built for PaperMC servers, PaperChat maintains conversation history per player and provides a seamless bridge between Minecraft players and modern AI capabilities.
Project Philosophy
PaperChat follows the "run it yourself" philosophy. By requiring your own AI API credentials and local deployment, you get:
- No Rate Limits - Your API keys, your usage quotas
- Complete Privacy - Player conversations never leave your infrastructure
- Full Control - Customize AI behavior, system prompts, and response filtering
- No Dependencies - No external services beyond the AI providers themselves
Features
- Multi-Provider AI Support: Automatic registration of Google Gemini and OpenAI providers with easy extensibility
- Persistent Conversation History: Per-player chat sessions with configurable history limits
- Smart Error Handling: User-friendly error messages with automatic response recovery
- Configurable System Prompts: Define AI behavior and response formatting rules
- Input Validation: Character limits
- Asynchronous Processing: Non-blocking AI requests to maintain server performance
- Docker Ready: Complete containerized deployment with Minecraft server bundled in
Configuration
PaperChat is configured through either environment variables:
| Variable | Description | Value |
|---|---|---|
PAPERCHAT_API_KEY |
Your AI provider API key | your-api-key (required only by your provider. If an AI provider does not require an API key, you can leave this blank) |
PAPERCHAT_MAX_HISTORY |
Max number of past requests to be saved per player | Conversation history limit |
PAPERCHAT_PROVIDER |
One of the available AI providers | AI provider (see more at Available Providers) |
PAPERCHAT_MODEL |
Any LLM that a provider provides | Model to use (required only by your provider. If an AI provider does not require a model to be set, you can leave this blank) |
PAPERCHAT_TEMPERATURE |
Response creativity (0.0-1.0) | 0.7 |
PAPERCHAT_TIMEOUT |
Request timeout in seconds | 30 |
PAPERCHAT_MAX_INPUT_CHARACTERS |
Maximum input message length | 100 |
PAPERCHAT_MAX_OUTPUT_TOKENS |
Maximum response length | 4096 |
PAPERCHAT_SYSTEM_PROMPT |
Custom system prompt for AI behavior | Your custom prompt (leaving empty uses default system prompt) |
Or config.yml file located in the data/plugins/PaperChat/ directory:
ai:
api-key: "" # You can leave it empty if your provider does NOT require an API key
provider: "google"
model: "gemini-2.5-flash" # You can leave it empty if your provider does NOT require a model parameter. However, at the moment this is only true for HackClub provider
temperature: 0.7
timeout: 30
max-output-tokens: 4096
system-prompt: "" # Include your custom system prompt here
# NOTE: setting a system prompt here will overwrite the current prompt
# If left empty, the default system prompt will be used
# Chat Configuration
chat:
max-history: 5
max-input-characters: 100
Configuration in config.yml matches the environment variables. If both are set, the environment takes precedence.
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.21, 1.21.1, 1.21.2
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Modrinth — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
- Ships as paperchat-1.1.0-beta.jar — drop this file into the mods folder
- Download size: 2.9 MB
- Download link checked 10 Sept 2026 — working
These come from our own check of the pack file, not from the source page.