MCServerFinder Java API (In development)

The official API implementation in Java for the MCServerFinder platform. This API allows server owners and developers to etrieve and update information about Minecraft servers on MCServerFinder.

What is MCServerFinder?

MCServerFinder is a platform, launched in April 2025, for discovering Minecraft servers. It features curated server listings across categories such as PvP, Creative, Adventure, Minigames, etc. Including real-time server leaderboards, community feedback, and trending picks. MCServerFinder makes it easy for players to find their next favorite server.

Documentation

Click here to check out the API documentation. (Heavily subject to change)

Usage

You may use the Ultimis repository to download one or more of the following as a dependency artifact:

• mcsf-api
• mcsf-api-transport-core

Maven

<repositories>
    <repository>
        <id>ultimis</id>
        <url>https://repo.ultimismc.com/repository/makera/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>gg.makera</groupId>
        <artifactId>mcsf-api</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

repositories {
    maven("https://repo.ultimismc.com/repository/makera/")
}

dependencies {
    implementation("gg.makera:mcsf-api:0.1.0-SNAPSHOT")
}

Example:

public final class Example {

    public static void main(String[] args) {
        // Note: Given that CompletableFuture#join is a blocking operation, we'll be using it to prevent the
        // MCSFAPI instance from closing before we've received a response. Use #thenAccept instead.

        // Create a new MCSFAPI instance with an API key

        try (MCSFAPI mcsfAPI = MCSFAPIFactory.create("your-api-key-here")) {
            // Fetch server information by server id, then wait for a response.
            ServerInfoResponse serverInfoResponse = mcsfAPI.getServerInfo(22).join();

            // Get the server object from the response.
            Server server = serverInfoResponse.getServer();

            System.out.println("Server Name: " + server.getName());
            System.out.println("Server IP address: " + server.getIpAddress() + ":" + server.getPort());
            System.out.println("Server Version: " + server.getVersion()); // e.g "1.8.9 (47)"
            System.out.println("Server Players: " + server.getOnlinePlayers() + "/" + server.getMaximumPlayers());

            // Leaderboards
            // Fetch server leaderboard by server id and leaderboard id, then wait for a response.
            LeaderboardInfoResponse leaderboardInfoResponse = mcsfAPI.getLeaderboardInfo(22, "kills").join();

            // Get the leaderboard object from the response
            LeaderboardInfoResponse.Leaderboard leaderboard = leaderboardInfoResponse.getLeaderboard();

            // Print leaderboard entries
            System.out.println("Kills Leaderboard:");
            for (LeaderboardInfoResponse.Leaderboard.Entry entry : leaderboard.getEntries()) {
                int position = entry.getPosition();

                String playerName = entry.getPlayerName();
                int value = entry.getValue();

                System.out.println("- #" + position + " - " + playerName + " - " + value); // e.g: #1 - DirectPlan - 100
            }

        } catch (Exception e) {
            // An internal error occurred. Always ensure that you properly handle exceptions.
            throw new RuntimeException(e);
        }
    }
}