{"id":39604827,"url":"https://github.com/scrayosnet/mcexport","last_synced_at":"2026-01-18T07:58:50.717Z","repository":{"id":264067666,"uuid":"885912571","full_name":"scrayosnet/mcexport","owner":"scrayosnet","description":"Minecraft Server Prometheus Exporter","archived":false,"fork":false,"pushed_at":"2025-11-26T13:26:38.000Z","size":339,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-11-29T09:48:57.716Z","etag":null,"topics":["exporter","minecraft","minecraft-java","observability","ping","prometheus","prometheus-exporter","protocol","rust","server-list-ping"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scrayosnet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-09T18:08:49.000Z","updated_at":"2025-11-26T13:11:47.000Z","dependencies_parsed_at":"2024-12-28T01:17:45.283Z","dependency_job_id":"37d9f750-f0fd-45c8-b29c-1074ed821af4","html_url":"https://github.com/scrayosnet/mcexport","commit_stats":null,"previous_names":["scrayosnet/mcexport"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/scrayosnet/mcexport","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrayosnet%2Fmcexport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrayosnet%2Fmcexport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrayosnet%2Fmcexport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrayosnet%2Fmcexport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scrayosnet","download_url":"https://codeload.github.com/scrayosnet/mcexport/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrayosnet%2Fmcexport/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28533586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["exporter","minecraft","minecraft-java","observability","ping","prometheus","prometheus-exporter","protocol","rust","server-list-ping"],"created_at":"2026-01-18T07:58:50.025Z","updated_at":"2026-01-18T07:58:50.708Z","avatar_url":"https://github.com/scrayosnet.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![The official Logo of mcexport](.github/images/logo.png \"mcexport\")\n\n![A visual badge for the latest release](https://img.shields.io/github/v/release/scrayosnet/mcexport \"Latest Release\")\n![A visual badge for the workflow status](https://img.shields.io/github/actions/workflow/status/scrayosnet/mcexport/docker.yml \"Workflow Status\")\n![A visual badge for the dependency status](https://img.shields.io/librariesio/github/scrayosnet/mcexport \"Dependencies\")\n![A visual badge for the Docker image size](https://ghcr-badge.egpl.dev/scrayosnet/mcexport/size \"Image Size\")\n![A visual badge for the license](https://img.shields.io/github/license/scrayosnet/mcexport \"License\")\n\nmcexport is a [Prometheus][prometheus-docs] prober exporter to query the publicly available information on arbitrary\nMinecraft servers through the official [ping protocol][ping-protocol-docs]. Unlike many other available exporters, this\nexporter is explicitly designed to query Minecraft servers from the outside.\n\nThe idea is similar to the official [Blackbox exporter][blackbox-exporter], but mcexport is specialized in probing\nMinecraft servers along with their publicly available Server List information. It supports the Minecraft protocol for\nall servers that are using Minecraft version 1.7 and above.\n\n## Motivation\n\nWhile there are many Minecraft-related exporters available at GitHub, there's none that use the\n[Multi-Target Exporter Pattern][multi-target-exporter-docs] and that can be used without exposing [RCON][rcon-docs].\nInstead of exposing the internal processes and metrics of a single Minecraft server, mcexport probes any requested\nMinecraft server through the publicly available data.\n\nAdditionally, mcexport was developed in [Rust][rust-docs], enabling great performance and therefore allowing to scrape\nserver metrics on a large scale. Combined with its well-tested reliability and hardened security, this makes large-scale\nanalysis of the Minecraft server ecosystem possible. Therefore, mcexport can be seen as a specialization of the official\n[Blackbox exporter][blackbox-exporter] that offers fast and efficient Minecraft metric probing.\n\nThe difference between mcexport and other existing solutions like\n[sladkoff/minecraft-prometheus-exporter][sladkoff-exporter], [cpburnz/minecraft-prometheus-exporter][cpburnz-exporter]\nand [dirien/minecraft-prometheus-exporter][dirien-exporter] is that those specialize in aggregating detailed metrics on\na single Minecraft server (either as a plugin, mod or external service) while mcexport does aggregate only public data\nabout dynamically submitted Minecraft servers.\n\nThe only existing solution that also supports dynamic probing is\n[Scientistguy/minecraft-prometheus-exporter][scientist-exporter], which requires [RCON][rcon-docs] to be enabled. That\nwas not an option, as we want to scrape metrics from servers that we have no control over. Therefore, mcexport is the\nonly solution for this scenario, offering dynamic probing on public Minecraft servers without any configuration or\nnecessary adjustments.\n\nSince metrics are bound to a specific instant in time, mcexport needed to be lightweight, scalable and hardened to be\nused as a reliable exporter in aggregating data. We offer robust container images and wanted to minimize any\nconfiguration and flags as much as possible. Any configuration is only done within Prometheus, making mcexport\nready for [Kubernetes][kubernetes-docs] from the get-go through [Probe][probe-docs].\n\n## Feature Highlights\n\n* Scrape multiple Minecraft servers through the public [Server List Ping protocol][ping-protocol-docs].\n* Expose information about the supported versions, current and maximum player count, latency and player samples.\n* Configure the targets and scrape intervals directly within Prometheus.\n* Start with zero configuration, no external resources or dependencies for mcexport.\n* Use it without applying any changes to the queried Minecraft servers.\n\n## Available Modules\n\nTo select a specific protocol version to ping a target, you can use the `module` field of the [Probe Spec][probe-docs]\nand set it to the required [protocol version number][pvn-docs]. Any number (negative and positive) is supported and\nwill be sent as the desired protocol version to the target. mcexport supports the latest iteration of the\n[Server List Ping protocol][ping-protocol-docs] that all servers since Minecraft 1.7 use.\n\nIf no module is specified explicitly, the most recent version at the time of the last release is used instead (if not\nexplicitly configured). Therefore, this may not be the latest version at any time, but at least a somewhat recent\nversion. You can override the version with the `module` field until a new release is created.\n\nIdeally, we could use (and fall back to) `-1` as the protocol version, as that is recommended to use, when determining\nthe appropriate/maximum supported version of a server. However, our practical tests revealed that only very few servers\nwould support this convention and would just reply with `-1` on their side, meaning unsupported. And servers that\nsupport `-1` also support specifying a recent version. Therefore, the \"somewhat recent\" version is the best we can do by\ndefault and without further configuration.\n\n## Getting Started\n\n\u003e [!WARNING]\n\u003e While mcexport is stable, please view the individual releases for any version-specific details that need to be\n\u003e considered while deploying. Changes are performed in adherence to [Semantic Versioning][semver-docs].\n\n### Setup mcexport\n\nBefore any Minecraft servers can be probed, we first need to set up mcexport on the corresponding machine. This does not\nhave to be the machine of the probed targets, but instead, it will probably be the same system that Prometheus runs on.\n\n#### From Binaries\n\nTo run mcexport from a binary file, download the appropriate binary from our [releases][github-releases], make it\nexecutable and run it within the shell of your choice:\n\n```shell\nchmod +x mcexport\n./mcexport\n```\n\n#### Using Docker\n\nTo run mcexport within Docker, we can use the images that we release within our [Container Registry][github-ghcr].\nThose images are hardened and provide the optimal environment to execute mcexport in a containerized environment.\n\n```shell\ndocker run --rm \\\n  -p 10026/tcp \\\n  --name mcexport \\\n  ghcr.io/scrayosnet/mcexport:latest\n```\n\n#### Using Kubernetes\n\nTo deploy mcexport on Kubernetes using Helm, you can use our official Helm chart from GitHub Container Registry:\n\n```shell\nhelm install mcexport oci://ghcr.io/scrayosnet/helm/mcexport --version 1.0.0\n```\n\nYou can customize the deployment by providing your own values:\n\n```shell\nhelm install mcexport oci://ghcr.io/scrayosnet/helm/mcexport --version 1.0.0 -f values.yaml\n```\n\nAlternatively, you can create your own deployment using [Kustomize][kustomize-docs] or any other tooling of your choice.\n\n### Check Setup\n\nTo verify whether everything works as expected, we can invoke the following command on the same machine and observe the\nreported result:\n\n```shell\ncurl --request GET -sL --url 'http://localhost:10026/probe?target=mc.justchunks.net'\n```\n\nIf the result shows any metrics, mcexport is now setup successfully and can be used to probe Minecraft servers.\n\n### Configure Prometheus\n\nNow that mcexport is working as expected, we need to configure Prometheus to probe any Minecraft server targets.\nDepending on the individual setup, this can be done in one of those ways:\n\n#### Normal Configuration\n\nIn a normal (non-Kubernetes) deployment of Prometheus, we can probe any Minecraft server with a scrape\nconfiguration like this:\n\n```yaml\nscrape_configs:\n- job_name: \"mcexport\"\n  scrape_interval: 60s\n  scrape_timeout: 30s\n  static_configs:\n  - targets:\n    - 'mc.justchunks.net'\n    - 'example.com'\n```\n\n#### CRD-based Configuration\n\nAssuming, there's a namespace `mcexport` with a deployment of mcexport, and a corresponding service `mcexport` is in\nthat namespace, that exposes the mcexport instances internally, we can probe metrics with this CRD configuration\nusing the [Probe][probe-docs] resource:\n\n```yaml\napiVersion: monitoring.coreos.com/v1\nkind: Probe\nmetadata:\n  name: mcexport\n  namespace: mcexport\nspec:\n  prober:\n    url: 'mcexport.mcexport.cluster.local:10026'\n  interval: 60s\n  scrapeTimeout: 30s\n  targets:\n    staticConfig:\n      static:\n      - 'mc.justchunks.net'\n      - 'example.com'\n```\n\nDepending on your setup, you may also need to add a label, so that the configuration is picked up by your Prometheus\ninstance. If you've installed it through the `kube-prometheus-stack` helm chart, it could, for example, be\n`release: kube-prometheus-stack`. You can check the required labels in your Prometheus CRD.\n\n### Configuration Tweaking\n\nTo modify the behavior and global values of mcexport, CLI flags and environment variables may be used. To get an\noverview of the available settings and their respective keys, run the following command:\n\n```shell\nmcexport --help\n```\n\nAll settings have sensible defaults that are suitable for production deployments of mcexport. Still, tweaking those\nsettings can be beneficial for debugging or specific runtime models.\n\n## Reporting Security Issues\n\nTo report a security issue for this project, please note our [Security Policy][security-policy].\n\n## Code of Conduct\n\nParticipation in this project comes under the [Contributor Covenant Code of Conduct][code-of-conduct].\n\n## How to contribute\n\nThanks for considering contributing to this project! In order to submit a Pull Request, please read\nour [contributing][contributing-guide] guide. This project is in active development, and we're always happy to receive\nnew contributions!\n\n## License\n\nThis project is developed and distributed under the MIT License. See [this explanation][mit-license-doc] for a rundown\non what that means.\n\n[prometheus-docs]: https://prometheus.io/\n\n[ping-protocol-docs]: https://wiki.vg/Server_List_Ping\n\n[blackbox-exporter]: https://github.com/prometheus/blackbox_exporter\n\n[multi-target-exporter-docs]: https://prometheus.io/docs/guides/multi-target-exporter\n\n[rcon-docs]: https://wiki.vg/RCON\n\n[rust-docs]: https://www.rust-lang.org/\n\n[sladkoff-exporter]: https://github.com/sladkoff/minecraft-prometheus-exporter\n\n[cpburnz-exporter]: https://github.com/cpburnz/minecraft-prometheus-exporter\n\n[dirien-exporter]: https://github.com/dirien/minecraft-prometheus-exporter\n\n[scientist-exporter]: https://github.com/Sciencentistguy/minecraft-prometheus-exporter\n\n[kubernetes-docs]: https://kubernetes.io/\n\n[pvn-docs]: https://wiki.vg/Protocol_version_numbers\n\n[probe-docs]: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#monitoring.coreos.com/v1.Probe\n\n[semver-docs]: https://semver.org/lang/de/\n\n[github-releases]: https://github.com/scrayosnet/mcexport/releases\n\n[github-ghcr]: https://github.com/scrayosnet/mcexport/pkgs/container/mcexport\n\n[helm-chart-docs]: https://helm.sh/\n\n[kustomize-docs]: https://kustomize.io/\n\n[security-policy]: SECURITY.md\n\n[code-of-conduct]: CODE_OF_CONDUCT.md\n\n[contributing-guide]: CONTRIBUTING.md\n\n[mit-license-doc]: https://choosealicense.com/licenses/mit/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscrayosnet%2Fmcexport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscrayosnet%2Fmcexport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscrayosnet%2Fmcexport/lists"}