{"id":21597460,"url":"https://github.com/cerus/mchr","last_synced_at":"2025-10-04T22:20:26.770Z","repository":{"id":38001966,"uuid":"501830619","full_name":"cerus/mchr","owner":"cerus","description":"A Minecraft skin rendering service - Render any Minecraft skin with ease","archived":false,"fork":false,"pushed_at":"2022-06-12T21:42:36.000Z","size":42,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T00:11:11.597Z","etag":null,"topics":["java","minecraft","minecraft-api","minecraft-heads","minecraft-skin","minecraft-skin-renderer","minecraft-skins","web-service"],"latest_commit_sha":null,"homepage":"https://mchr.cerus.dev","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cerus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["cerus"]}},"created_at":"2022-06-09T22:48:18.000Z","updated_at":"2024-11-23T09:28:43.000Z","dependencies_parsed_at":"2022-09-12T15:53:22.268Z","dependency_job_id":null,"html_url":"https://github.com/cerus/mchr","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmchr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmchr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmchr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cerus%2Fmchr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cerus","download_url":"https://codeload.github.com/cerus/mchr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252584329,"owners_count":21771945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["java","minecraft","minecraft-api","minecraft-heads","minecraft-skin","minecraft-skin-renderer","minecraft-skins","web-service"],"created_at":"2024-11-24T18:09:03.600Z","updated_at":"2025-10-04T22:20:21.719Z","avatar_url":"https://github.com/cerus.png","language":"Java","readme":"# mchr\n\nMCHR (mc head render) is a simple Minecraft skin rendering service. MCHR can be configured to use a variety of skin providers. While other services\nsuch as Minotar and Crafatar only allow you to render the skin of usernames / uuids, MCHR allows you to render skins that are not in use by players.\n\nPublic instance: https://mchr.cerus.dev\n\n## Endpoints\n\n### V1\n\nBase path: `/v1`\n\n**GET /info**\\\nGet information about the MCHR instance\n\n**GET /render/{skin_key}**\\\nRender a head\n\nQuery params:\n\n- (Optional) `skin`\n    - The skin provider\n    - Allowed values: id of a registered skin provider\n    - Default: `mojang`\n- (Optional) `renderer`\n    - The renderer\n    - Allowed values: `flat`, `isometric`\n- (Optional) `size`\n    - The desired with and height\n    - Examples: 128, 512, 16\n    - Default: `8`\n- (Optional) `overlay`\n    - Whether the hat overlay should be rendered or not\n    - Allowed values: `true`, `false`\n    - Default: `true`\n- (Optional) `filter`\n    - The filters (concatenate filters with ,)\n    - Allowed values: id of a registered filter\n\n**GET /skins**\\\nList all available skin providers\n\n## Usage\n\nExample usage:\n\n\u003cdetails\u003e\n  \u003csummary\u003eRender a flat head using a Mojang skin\u003c/summary\u003e\n  \u003ca href=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75\"\u003ehttps://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75\" alt=\"Rendered image\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRender an isometric head using a Mojang skin\u003c/summary\u003e\n  \u003ca href=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\"\u003ehttps://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\" alt=\"Rendered image\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRender an isometric head using a Mojang skin of size 256x256\u003c/summary\u003e\n  \u003ca href=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\u0026size=256\"\u003ehttps://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\u0026size=256\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://mchr.cerus.dev/v1/render/74d1e08b0bb7e9f590af27758125bbed1778ac6cef729aedfcb9613e9911ae75?renderer=isometric\u0026size=256\" alt=\"Rendered image\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRender a flat head using a Minotar skin of size 128x128 without overlay\u003c/summary\u003e\n  \u003ca href=\"https://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026overlay=false\"\u003ehttps://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026overlay=false\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026overlay=false\" alt=\"Rendered image\"\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eRender a flat head using a Minotar skin of size 128x128 with a grayscale filter\u003c/summary\u003e\n  \u003ca href=\"https://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026filter=grayscale\"\u003ehttps://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026filter=grayscale\u003c/a\u003e\u003cbr\u003e\n  \u003cimg src=\"https://mchr.cerus.dev/v1/render/Cerus_?skin=minotar\u0026size=128\u0026filter=grayscale\" alt=\"Rendered image\"\u003e\n\u003c/details\u003e\n\n## Installation\n\n### Using docker-compose\n\nCreate a `.env` file with the following contents (change the values if needed):\n\n```\nMCHR_HOST=\"0.0.0.0\"\nMCHR_PORT=\"8080\"\nMCHR_IMAGE_CACHE_EXPIRATION=\"300\"\nMCHR_MAX_REQUESTS=\"120\"\nMCHR_RATE_LIMITER_EXPIRATION=\"60\"\n```\n\nCreate a `docker-compose.yml` file with the following contents:\n\n```yaml\nservices:\n  mchr:\n    container_name: \"mchr\"\n    restart: always\n    image: \"openjdk:17\"\n    ports:\n      - \"8099:8080\" # Change 8099 to the port you want this to be exposed on\n    volumes:\n      - ./data:/opt/data\n    command: \"bash -c \\\"cd /opt/data \u0026\u0026 java -jar mc-head-render-*.jar\\\"\"\n    environment:\n      MCHR_IMAGE_CACHE_EXPIRATION: \"${MCHR_IMAGE_CACHE_EXPIRATION}\"\n      MCHR_MAX_REQUESTS: \"${MCHR_MAX_REQUESTS}\"\n      MCHR_RATE_LIMITER_EXPIRATION: \"${MCHR_RATE_LIMITER_EXPIRATION}\"\n      MCHR_HOST: \"${MCHR_HOST}\"\n      MCHR_PORT: \"${MCHR_PORT}\"\n```\n\nAfter this run `docker-compose up -d` to start the container.\n\n## Configuration\n\n### Environment variables\n\nMCHR_HOST: The web server host\\\nMCHR_PORT: The web server port\\\nMCHR_IMAGE_CACHE_EXPIRATION: The expiration of cached skins in seconds\\\nMCHR_MAX_REQUESTS: Maximum allowed request in the configured amount of time\\\nMCHR_RATE_LIMITER_EXPIRATION: The rate limit period in seconds\n\n### Skin providers\n\nSkin providers can be configured using the `skin_providers.json` file. Example configuration:\n\n```json5\n{\n  \"skin_provider\": {\n    \"namemc\": {\n      // Get NameMC skin by id\n      \"url\": \"https://s.namemc.com/i/%s.png\",\n      \"pattern\": \"[\\\\da-f]{16}\"\n    },\n    \"crafatar\": {\n      // UUID to skin\n      \"url\": \"https://crafatar.com/skins/%s\",\n      \"pattern\": \"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\"\n    },\n    \"minotar\": {\n      // Username / UUID to skin\n      \"url\": \"https://minotar.net/skin/%s\",\n      \"pattern\": \"(([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})|([a-zA-Z0-9_]{3,16}))\"\n    }\n  }\n}\n```\n\n## Building from source\n\nYou need:\n\n- Java 17\n- Maven\n- Git\n\n1. Clone the repository (`git clone https://github.com/cerus/mchr`)\n2. Cd into the cloned repo (`cd mchr`)\n3. Build the project (`mvn clean package`)\n4. The build artifact can be found in `target/` (`mc-head-render-VERSION.jar`)\n\n## Reporting issues\n\nPlease [open a new issue](https://github.com/cerus/mchr/issues/new) to report bugs / request features etc.\n\n## Contributing\n\nPlease take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.\n\n## Buy me a coffee\n\n[:heart: Sponsor me on GitHub](https://github.com/sponsors/cerus)","funding_links":["https://github.com/sponsors/cerus"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerus%2Fmchr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcerus%2Fmchr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcerus%2Fmchr/lists"}