Skip to main content
Glama
deenesjakoruzh
lanlan3292

molanko-mcp-avatar-generator

by lanlan3292
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
JavaScript
Local

molanko-mcp-avatar-generator

MCP server for molanko-avatar-generator.

The server exposes one tool:

  • generate_avatar — generate a Molanko Avatar from a provided image or a Minecraft player name/UUID, then return the generated PNG as an MCP image result.

A source is required: provide exactly one of image or minecraftPlayer.

Run

npm install
npm start

The server uses MCP stdio transport, so it can be launched by MCP clients that support local stdio servers.

Related MCP server: mcp-xmorf

Tool: generate_avatar

Source

Provide exactly one:

  • image — MCP-style image object: { "type": "image", "data": "<base64>", "mimeType": "image/png" }

  • minecraftPlayer — Minecraft username or UUID, with or without UUID hyphens. The server resolves the current skin using Mojang's profile and session APIs, then downloads the skin directly from the texture URL supplied by Mojang.

Examples:

{ "minecraftPlayer": "Notch" }
{ "minecraftPlayer": "069a79f4-44e9-4726-a5be-fca90e38aaf5" }

If both image and minecraftPlayer are supplied, the request is rejected rather than silently choosing one.

Options

  • scale — nearest-neighbor output scale

  • outlineMode — outline radius; 0 disables the outline

  • outlineColor — auto, auto_darker, auto_lighter, or a hex color

  • bgColor — auto, auto_lighter, auto_darker, or a hex color

  • fillBackground — whether to fill the output background

  • upscale48 — render the 32x32 avatar centered on a 48x48 canvas

  • averageColor — optional override for the color used by automatic outline/background colors; use auto, #RRGGBB, or #RGB

averageColor is not a separate tool. It overrides the generator's automatically calculated average color. If omitted or set to auto, the underlying generator calculates the average color from the source skin. A hex value is parsed into { r, g, b } and passed to molanko-avatar-generator as averageColor.

The result is returned as an MCP image content item containing a PNG.

Minecraft player resolution

minecraftPlayer follows the same basic approach as the Android avatar generator: a UUID is normalized directly; a username is resolved through api.mojang.com/users/profiles/minecraft/{name}; the UUID is then resolved through Mojang's session profile API to obtain the player's textures property and skin URL. No third-party skin-rendering or skin-mirroring service is required.

The server reports useful failures such as invalid player identifiers, player not found, missing skin texture, Mojang rate limits, Mojang server errors, and network/download errors.

Architecture

This repository is intentionally a thin MCP adapter. Minecraft player resolution and avatar rendering happen server-side, while the actual avatar rendering remains in molanko-avatar-generator.

Available Tools

1 tool
generate_avatarGenerate Molanko AvatarA

Generate a Molanko Avatar. Provide exactly one source: image or minecraftPlayer. minecraftPlayer accepts a Minecraft username or UUID (with or without hyphens); the server resolves the current skin through Mojang APIs. Returns the generated PNG as an MCP image result.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageNoA source Minecraft skin/image.
scaleNoNearest-neighbor output scale.
bgColorNoBackground color: auto, auto_lighter, auto_darker, or a hex color.auto
upscale48NoRender the avatar on a 48x48 canvas with the 32x32 avatar centered.
outlineModeNoOutline radius in pixels. 0 disables the outline.
averageColorNoOverride the color used by automatic outline/background colors. Use auto (default), #RRGGBB, or #RGB.
outlineColorNoOutline color: auto, auto_darker, auto_lighter, or a hex color.auto
fillBackgroundNoWhether to fill the background.
minecraftPlayerNoMinecraft username or UUID, with or without hyphens. The server fetches the current skin through Mojang APIs.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the output format (PNG as MCP image result) and the Minecraft skin resolution process. However, it does not mention error conditions, rate limits, or what happens if both sources are provided, which leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the purpose and a critical usage rule. No redundant or filler content; every clause contributes to understanding how to invoke the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters and no output schema, the description covers the essential aspects: the two source options and the return type. It does not elaborate on default behaviors of rendering options (scale, background, outline), but the schema fully documents these, so the description is sufficiently complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline 3 applies. The description adds meaningful context beyond the schema by specifying the 'exactly one source' constraint and explaining how minecraftPlayer is resolved via Mojang APIs, which goes beyond the parameter's own schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Generate') and the specific resource ('Molanko Avatar'). It also identifies the two mutually exclusive source types, clarifying the tool's scope even without sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'Provide exactly one source', which is a direct usage rule. It also explains how minecraftPlayer works (username/UUID, Mojang API resolution). No alternatives are mentioned because no sibling tools exist, so this is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedgenerate_avatar
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool, there is no potential for confusion or overlap. The tool's purpose is clearly defined and unambiguous.

Naming Consistency5/5

The single tool uses a clear verb_noun naming convention (generate_avatar) which is consistent and self-explanatory, even with only one tool.

Tool Count3/5

The server has just one tool, which feels thin for a typical MCP server. However, it may be appropriate for the narrow scope of avatar generation, so it borders on acceptable.

Completeness5/5

The tool covers the domain comprehensively by accepting both image and Minecraft player sources, and there are no obvious missing operations for avatar generation.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers