StatsMC: Public API for Minecraft Player Statistics

What Is StatsMC and Why Your Server Needs It

Every Minecraft server owner knows the thrill of tracking player progress. From counting blocks mined to tallying mob kills, statistics breathe life into a world of blocks and biomes. StatsMC is a lightweight server plugin that exposes vanilla player statistics through a clean, REST-like API. Instead of digging through server files or relying on bulky admin tools, you can query live data with simple HTTP requests. Whether you want to build a Discord leaderboard, create a web dashboard, or just satisfy your curiosity, StatsMC delivers the numbers you need in JSON format.

How the StatsMC API Works

At its core, StatsMC listens on a dedicated port—11236 by default—and responds to specific endpoints. The plugin does not alter gameplay or add new mechanics; it simply reads the built-in statistics that Minecraft already tracks for every player. You must ensure port 11236 is open in your hosting settings, and then the API becomes accessible at <ip>:11236/mcstats/.... The response is always a dictionary mapping player names to their stat values, or an error message if something goes wrong.

Main Endpoint: /mcstats/all_players

This is the workhorse of StatsMC. You supply a statistic argument—like DEATHS, MINE_BLOCK, or KILL_ENTITY—and optionally a second argument depending on the statistic. For example, MINE_BLOCK requires a block_type (the material name), while KILL_ENTITY needs an entity_type. The API validates your input and returns clear error messages if you use an invalid statistic or forget a required parameter. This makes debugging straightforward, even for beginners.

Consider a few practical queries:

• Deaths leaderboard: /mcstats/all_players?statistic=DEATHS returns {"Notch":4,"_jeb":5}.
• Stone mined: /mcstats/all_players?statistic=MINE_BLOCK&block_type=STONE gives you the exact count per player.
• Creepers slain: /mcstats/all_players?statistic=KILL_ENTITY&entity_type=CREEPER shows who is the best creeper hunter.

Invalid requests are handled gracefully. If you ask for a non-existent statistic like TIMES_DIED, the API responds with {"error": "Invalid 'statistic' value"}. If you forget a required argument, it tells you exactly what is missing. This thoughtful design saves hours of guesswork.

Discovery Endpoints: /mcstats/list, /mcstats/list/materials, /mcstats/list/entities

Not sure which statistics are available? The /mcstats/list endpoint returns a full array of tracked stats—over 80 entries ranging from DAMAGE_DEALT to STRIDER_ONE_CM. Similarly, /mcstats/list/materials provides all valid block and item types (more than 1200, including every stone variant and potted plant), and /mcstats/list/entities lists every entity from DROPPED_ITEM to PLAYER. These discovery endpoints make it easy to build dynamic interfaces that adapt to any Minecraft version.

Integrating StatsMC with Discord Bots and Web Dashboards

The original purpose of StatsMC was to power a Discord bot that displays player statistic tops. By fetching data from the API, the bot can post leaderboards in a channel, compare players, or even award roles based on achievements. But the API is completely standalone—you can use it with any external tool that can make HTTP requests. For instance, a simple Python script can pull the data and render it on a web dashboard, or you could integrate it into a server control panel. The JSON format is clean and easy to parse, making it a versatile building block for custom server analytics.

If you are running a modded server and want to track custom statistics alongside vanilla ones, you might need a launcher that simplifies mod management. Many server admins find that the foxygame.net launcher offers a convenient, flexible, and modern way to install server-side plugins directly from its menu, saving time and reducing configuration headaches. This kind of tool pairs well with StatsMC, letting you focus on building engaging stat-driven features for your community.

Setting Up StatsMC on Your Server

Installation is straightforward. Place the plugin JAR into your server's plugins folder and restart. The only configuration requirement is opening port 11236 in your firewall or hosting panel. Once the server is running, you can test the API with a browser or command-line tool like curl. The plugin is designed to be lightweight, so it won't impact server performance even on large multiplayer worlds with dozens of players.

Common Use Cases and Creative Ideas

• Leaderboards: Display top miners, fighters, or explorers on a website or in-game via holograms.
• Event tracking: During a server-wide competition, monitor progress in real time.
• Player milestones: Automatically reward players when they reach certain stat thresholds.
• Data analysis: Export statistics to study how players interact with your world—which biomes they visit, which mobs they avoid, and which blocks they break most often.

Understanding the API Responses and Error Handling

Every response is a JSON object. On success, keys are player names and values are integers. On failure, the object contains a single error key with a human-readable message. The API checks arguments in a specific order: first the statistic name, then the required secondary argument (block_type or entity_type). This means if both the statistic and the material are invalid, you will see an error about the statistic first. The system also catches impossible combinations—like trying to count how many times a player killed a dropped item—and still returns a valid response (usually zeros), because Minecraft internally tracks such oddities.

Why StatsMC Stands Out Among Server Utilities

Many server tools offer statistics, but few expose them through such a minimal, focused API. StatsMC does one thing and does it well: it reads vanilla player stats and serves them over HTTP. There is no bloat, no unnecessary database, and no complex configuration. The plugin respects Minecraft's own stat tracking, so it works with any version that supports the underlying statistics system. Whether you run a small survival server or a large network, StatsMC gives you the raw data to build your own leaderboards, rewards, and analytics.

Conclusion

StatsMC transforms hidden player statistics into accessible, actionable data. With its clean API, built-in validation, and discovery endpoints, it empowers server owners to create engaging community features without diving into complex plugin development. From Discord leaderboards to custom web dashboards, the possibilities are limited only by your imagination. By opening port 11236 and sending a few HTTP requests, you unlock a wealth of information about how your players interact with the world—every block broken, every mob slain, and every centimeter traveled. For any server admin who values player engagement and data-driven insights, StatsMC is an essential addition to the toolkit.