column01 / mcconsoleapi

An asynchronous HTTP based web API for running Minecraft servers targeted at Developers and sys admins

MCConsoleAPI

MCConsoleAPI is an HTTP API wrapper for Minecraft servers that gives you the power to create automation and tools for minecraft servers without needing to know a specific programming language. Make simple HTTP requests to the backend and accomplish any task you want in any language you want!

Note

This project is a WIP and is not guaranteed to be secure in any way. Steps have been taken to mitigate some attack vectors, but no application is 100% safe. This software is provided AS IS without warranty of any kind. Any issues you have, please report them on the issues page with any relevant information.

Setup and Installation

Pre-requisites

1. Install Python (>=Python 3.8 tested on 3.12.3)
   • This project uses FastAPI which requires Python 3.8+
2. Download the project
   • You can do this by cloning the repo or clicking this link
   • If you downloaded it as a ZIP file, please extract it to a folder somewhere logical
3. Install Requirements
   • Open a command prompt or terminal (google it)
   • Change to the directory of the program: cd /path/to/extracted/download/ (or P:\ath\to\extracted\download\ on windows)
   • Windows: python -m pip install -r requirements.txt
   • Unix: pip3 install -r requirements.txt

Configuration

1. Copy config_template.toml and place it into the root directory of your server (where server.properties and the server jar are located) and rename it to config.toml
2. Open the newly copied and renamed config.toml in your text editor of choice, verify all the settings are set how you would like.
   • Things should be commented as well as I can (and if you need clarification, please create an issue and ask)
   • The main things to check here are the server host and the port, these are the IP and Port the API will use to serve HTTP requests. This is also the info you need to develop any tools around it
   • After that, ensure the java_path, server_jar and jvm_args have anything you need setup for your instance.

As of now, there isn't a convenient way to run the program other than from the main program folder.

This will change in the future as development continues.

For now, you can start a server using this command:

• Windows: python main.py --path 'C:\path\to\server\root'
• Linux: python3 main.py --path '/path/to/server/root'

Getting your Admin API key

When you first run the program, you will see a section print out in the console that looks like this:

================
ADMIN API KEY: ADMIN-API-KEY
================

Copy this somewhere, if you lose it you will need to regenerate it. This API key is also the only API key that can issue a new API key, so you need it if you would like to authorize other clients to use your server's API.

The Admin (and any other API keys) are server specific. If you decide to host more than one server, you will need to run more than one instance of MCConsoleAPI. The API keys are stored in an SQLite3 database file in the server root (api_keys.db). If you ever lose your admin API key, or you need to regenerate your API keys in the event of a breach, just delete this file.

See the next section on viewing the API documentation where you can also see the endpoint for creating a new API key. It is recommended you do this immediately and DO NOT use the Admin API key for every day tasks.

Reading the API docs

Once you have started the program and it starts your minecraft server, open your web browser and navigate to the host and port that was printed into the console.

You should see a page saying: {"line":"Connected to MCConsoleAPI! You can read the server output at '/output'"}, this means everything is working correctly!

To get to the docs, you just need to go to the /docs endpoint, these are automatically generated by the program and will update for every change that is made to the routes for the program.