Hypixel SkyBlock MCP

An AI-facing Model Context Protocol server for Hypixel SkyBlock data. It fetches profile data, public resources, Bazaar prices, auctions, museum/garden data, HOTM/HOTF skill trees, merged storage search, and base64 gzipped NBT inventory payloads, then returns compact JSON that is easier for an AI assistant to use for guides and tips.

Requirements

• Node.js 22 or newer
• A Hypixel API key for private/profile endpoints

Get a key from the Hypixel Developer Dashboard and provide it as HYPIXEL_API_KEY.

Setup

Add the server to your MCP client config. The package ships a hypixel-skyblock-mcp binary, so npx can run it without a manual install:

{
  "mcpServers": {
    "hypixel-skyblock": {
      "command": "npx",
      "args": ["-y", "hypixel-skyblock-mcp"],
      "env": {
        "HYPIXEL_API_KEY": "your-key"
      }
    }
  }
}

See .env.example for the full list of supported environment variables (cache TTL, request timeout, optional lowest-BIN source).

Running from source

npm install
npm run build
node dist/server.js   # reads HYPIXEL_API_KEY from the environment

Development

npm test          # run the unit tests
npm run coverage  # run tests + enforce coverage thresholds
npm run check     # build + test (also runs automatically before publish)

GitHub Actions runs the build and the coverage gate on every push and pull request (.github/workflows/ci.yml). The coverage gate (configured in vitest.config.ts) is scoped to the deterministic, pure-logic modules; the network/orchestration layer that calls the live Hypixel API is verified manually rather than by unit tests.

Publishing is automated (.github/workflows/publish.yml): creating a GitHub Release whose tag matches the package.json version publishes the package to npm with provenance. Authentication uses npm Trusted Publishing (OIDC), so no NPM_TOKEN secret is required — configure a Trusted Publisher for this repo and workflow in the package's npm settings instead.

Tools

Player & profiles

• resolve_player: username/UUID normalization through Mojang.
• hypixel_player: network status, rank, login times, karma, and selected stats.
• skyblock_profiles: compact list of a player's SkyBlock profiles.
• skyblock_profile: one profile's AI-readable context with skills, progression, slayers, dungeons, pets, collections, essence, accessories, and optional decoded inventories.

Inventories & storage

• skyblock_inventory: decode wardrobe, armor, equipment, ender chest, backpacks, vault, sacks, bags, and loadouts.
• skyblock_storage: merged storage search across backpacks, ender chest, vault, sacks, and bags with item grouping and sack totals.

Progression & guides

• skyblock_audit: compact audit with official skill levels, full HOTM/HOTF perk trees, minions, bestiary, crimson isle, rift, essence, gear/loadouts (including essence cost to finish starring equipped gear, priced live), accessories, ranked gaps, and next actions.
• skyblock_guide_context: profile plus mayor and Bazaar economy signals for tailored advice.

World systems

• skyblock_museum: museum donations and value summary.
• skyblock_garden: garden plots, commissions, and composter data.

Economy & resources

• skyblock_networth: estimate a profile's net worth from liquid coins, decoded inventory/storage holdings, sacks, and supported item modifiers, priced with live Bazaar data. Returns a total, per-section breakdown, modifier breakdown, top items by value, and a pricing-coverage report.
• skyblock_item: look up one item by ID or name and get official metadata plus a live value (Bazaar buy/sell/spread/volume, lowest-BIN when configured, or a clear auction-only note). Set includeWiki: true to enrich the result with official Hypixel SkyBlock Wiki page URL, revision timestamp, and cleaned obtaining/upgrading/usage/history sections. Ambiguous searches return candidate IDs, and it resolves in-game names (e.g. "Necron's Chestplate") to canonical IDs.
• skyblock_resource: items, skills, collections, election/mayor, bingo, or news.
• skyblock_wiki_search: search the official Hypixel SkyBlock Wiki through its MediaWiki API.
• skyblock_wiki_page: fetch a specific official wiki page and return AI-readable section summaries from the page wikitext.
• skyblock_bazaar: Bazaar prices, volumes, and spread signals.
• skyblock_auctions: active pages, ended auctions, or keyed lookups.
• skyblock_essence_costs: exact essence, coin, and material cost to star up (or master-star) a dungeon/crimson item by SkyBlock ID, with an optional live-Bazaar coin estimate. Returns found: false with suggestions for unknown or non-upgradeable IDs.

Utilities

• decode_skyblock_nbt: decode a SkyBlock NBT payload.
• cache_clear: clear the in-memory response cache.

HOTM, HOTF, and storage

HOTM (Heart of the Mountain) is summarized in member.progression.hotm and skyblock_audit:

• HOTM level, powder totals, crystal states, selected ability
• Full unlocked perk list with human-readable names

HOTF (Heart of the Forest) is summarized in member.progression.hotf:

• Forest Whispers balance and spend
• Unlocked foraging perks and selected ability

Storage is best accessed through skyblock_storage:

{ "username": "Ventoy", "search": "enchanted diamond" }

{
  "username": "Ventoy",
  "skyblockIds": ["DIVAN_HELMET", "DIVAN_CHESTPLATE"],
  "sectionTypes": ["backpack", "ender_chest", "personal_vault"]
}

skyblock_inventory remains the tool for raw per-section NBT when you need slot-level detail.

Player ratings & metrics

skyblock_profile (per member) and skyblock_audit (ratings) expose the headline numbers players compare:

• Skill average (and fractional "true" average) over the eight counted skills: Farming, Mining, Combat, Foraging, Fishing, Enchanting, Alchemy, Taming.
• Total slayer XP and summed slayer levels, plus per-boss XP/level.
• Catacombs level, magical power, and SkyBlock level.

skyblock_audit and skyblock_guide_context also include a compact mayor summary: the active mayor, special-mayor flag, active perks, and the ongoing election leaderboard.

Net worth

skyblock_networth prices a profile from:

• Liquid coins (purse + bank).
• Items in decoded inventory, ender chest, backpacks, personal vault, wardrobe, armor, equipment, and bags, priced by SkyBlock ID via the Bazaar.
• Sacks, priced via the Bazaar.

On top of the base SkyBlock-ID price, skyblock_networth adds modifier value for enchantments, hot potato/fuming books, recombobulators, essence/master stars, socketed gemstones, and reforge stones (set includeModifiers: false to disable). Each modifier is valued at the SkyHelper-Networth "application worth" fraction of the live Bazaar price of the component (e.g. enchantments at 85%, essence at 75%, gemstones and reforge stones at 100%), and essence/master-star costs come from the official items resource's upgrade_costs. The response reports items.modifiers (total, byType breakdown, and unpricedComponents).

The modifier categories above are the ones currently modelled. SkyHelper values several more that this server does not yet add, so total is a conservative estimate for heavily upgraded items: gemstone slot-unlock costs, runes, dyes, pet items/pet levels, art of war/peace, power scrolls, and other cosmetic or upgrade consumables are excluded.

Modifier value is only added to items that already have a base price, so auction-only gear is undervalued unless a lowest-BIN source is configured. Read the coverage report (pricedPercent) to see how much of the profile could be priced, and treat total as an estimate.

Auction-only items are priced only when an external lowest-BIN source is configured via the SKYBLOCK_LOWEST_BIN_URL environment variable (a JSON map of { SKYBLOCK_ID: price }, e.g. a Moulberry-style lowest-BIN dump). Bazaar prices always take precedence over that source. Use priceBasis to switch between buy (market/replacement value, default) and sell (liquidation value).

Notes

Hypixel profile data depends on each player's in-game API settings. When fields are missing, the MCP returns privacy notes so the AI does not overclaim inventory, pet, collection, or skill state.

Skill levels use Hypixel's official /v2/resources/skyblock/skills tables (bundled in src/skill-tables.json). SkyBlock level uses the flat 100-XP-per-level formula, pet levels use the official per-rarity XP tables (Golden/Jade/Rose Dragons cap at level 200), and Garden level uses the real Garden XP table (15 levels, capping at 60,120 XP).

Essence upgrade costs (skyblock_essence_costs) come from the NotEnoughUpdates essencecosts.json constants (bundled in src/essence-costs.json). The dataset covers essence-funded stars (1–5 for dungeon gear, up to 10 for crimson/kuudra gear); Master Stars applied with Master Star items are noted but not priced.

For profile reviews, prefer skyblock_audit over skyblock_guide_context when you want compact gaps and next actions.

The server uses the official Hypixel Public API v2. Keyed endpoints use the API-Key header and report rate-limit headers when Hypixel provides them.