Skip to main content
Glama
Stardew Save MCP

Stardew Save MCP

by vehemont

sdv-mcp

This is a read-only MCP server that reads a Stardew Valley save and answers questions about it, and is pulls your most recent save data per-call. I recently got into the game with my wife and noticed I was spending more time reading the Stardew Wiki rather than playing, so I made this to answer the questions I had. It includes 58 tools, and also allows Stardew Wiki search through MediaWiki API. I made this with mainly vanilla in mind, so YMMV with mods.

CAUTION

This MCP is read-only and should not cause any issues, but safety first is always the best approach! Use a save copy first, not an original. Then once you feel comfortable, you can point it at your real save to receive the save-per-night updates.

Example questions that utilize the state of your save, tailoring responses to you depending on the season, day, location, and what you already have:

"What is my best money maker that I should be utilizing?"

"What should I focus on next?"

"Can anything be completed with what I have?"

"Best way to get coal?"

"Give me a priority step-by-step list on completing my fishing bundle."

"Where is the chest that has the pearl I need to gift to Clint?"

"How many sprinklers will I need to water all my Cauliflower seeds I have?"

Requirements

  • Python 3.10 or newer.

  • A Stardew Valley save file. The game stores saves at:

    • Windows: %APPDATA%\StardewValley\Saves\<FarmName>_<id>\<FarmName>_<id>

    • macOS/Linux: ~/.config/StardewValley/Saves/<FarmName>_<id>/<FarmName>_<id>

    Point the server at that save file or its folder (--save / --save-dir, or the SDV_SAVE_PATH / SDV_SAVE_DIR env var). The server never searches for saves on its own.

  • One Python dependency — the mcp SDK (mcp>=1.2.0,<2). Everything else uses the Python standard library (the wiki client is stdlib urllib), so there is nothing else to install.

  • uv — only needed for the recommended uvx install method below (it provides the uvx command). Install it from docs.astral.sh/uv. Not required if you instead pip install the package or run from this folder.

Install it with either:

  • uvx sdv-mcp (recommended — runs the published package directly, no manual install; requires uv), or

  • pip install sdv-mcp (the published package), or

  • pip install -r requirements.txt then python sdv_mcp_server.py (to run from this folder).

Keep the four modules in the same folder — the server imports the others from its own dir.

Related MCP server: stardew-mcp

Install into a client

Needs uv, pass a save folder/directory with --save-dir or just --save with the actual save file, which is just the same name as the folder/directory:

--save-dir example on Windows with Claude Desktop and proper JSON escapes:

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "uvx",
      "args": [
        "sdv-mcp", // use "sdv-mcp@latest" to always pull the latest version
        "--save-dir", "C:\\Users\\you\\AppData\\Roaming\\StardewValley\\Saves\\FarmName_437005740"
      ]
    }
  }
}

uvx pulls the package from PyPI. Pin a version with sdv-mcp==0.1.0, or install the latest dev build straight from git by adding "--from", "git+https://github.com/vehemont/sdv-mcp" before "sdv-mcp".

Alternative: run a local checkout

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "python",
      "args": [
        "/path/to/sdv-mcp/sdv_mcp_server.py",
        "--save-dir", "C:/Users/you/AppData/Roaming/StardewValley/Saves/FarmName_123456"
      ]
    }
  }
}

macOS/Linux use python3; pip install -r requirements.txt first.

Runs on stdio. You must point --save/--save-dir (or the env var) at the save you want; the server reads only that save and never scans your machine for others.

Disabling tools

By default, all tools are enabled. Any tool you consider cheating/unfair can be turned off so the model never sees it. Two knobs, both settable as a CLI arg (wins) or an env var:

  • Denylist — --disable-tools a,b,c or SDV_DISABLE_TOOLS=a,b,c. Serves everything except those.

  • Allowlist — --enable-tools a,b,c or SDV_ENABLE_TOOLS=a,b,c. Serves only those (disable is applied after).

{
  "mcpServers": {
    "sdv-mcp": {
      "command": "python",
      "args": [
        "/path/to/sdv-mcp/sdv_mcp_server.py",
        "--save-dir", "C:/Users/you/AppData/Roaming/StardewValley/Saves/FarmName_123456",
        "--disable-tools", "find_item,missing_museum,perfection"
      ]
    }
  }
}

Tools (46)

Save state

Tool

What

save_status

Save freshness: file path, last-modified time, age, in-game date. Every save-backed result also carries a _save stamp (in-game date + file mtime/size) so the model can tell if earlier data is stale — compare its _save.mtime_ns to a fresh save_status() (equal = current, different = re-run the tool)

overview

Date, players, shared money, lifetime earnings, deepest mine, version

players

Per-player levels, XP, XP-to-next, professions, spouse, backpack, house ({'players': [...]})

community_center

Rooms done/left, incomplete bundles + exact items needed, Vault status

museum

Donations / 95 + next milestone with its actual reward (60 = Rusty Key)

monster_goals

Guild eradication goals: kills vs target + reward ({'goals': [...]})

friendships

Villager hearts/points + spouse, per player

gift_log

Gifting planner: per-villager gifts today/this week (2/wk cap), status + full gift history (zero-count entries dropped)

player_stats

In-game Stats tab: all counters (steps, shipped, fish caught, geodes, quests...) + per-species monster kills

player_tools

Each player's tools + upgrade tier

wallet

Keys/special items (Rusty Key, Skull Key, Club Card, ...). 1.5 + 1.6 aware (reads mail flags)

unlocks

Which gated locations/vendors are reachable (Desert + Desert Trader, Sewers/Krobus, Skull Cavern, Casino, Quarry, Greenhouse, Minecarts, Movie Theater, Guild, Ginger Island) + how to unlock the rest

feed

Animals, silo hay, fiber, days of feed covered (+ fiber-as-grass-starters)

full_report

All of the above in one shot

Inventory + location

Tool

What

inventory

Backpacks + chests. full=True = all items; by_container=True = per-chest

processing

Held crops grouped fruit/veg/special by the save's own item category

machines

Inventory of placed machines (Furnace, Keg, Cask, Seed Maker, Kiln, Tapper, ...) by type with counts + state (ready/working/idle) + a by-location breakdown

buildings

Farm buildings + per-player farmhouse upgrades: barn/coop tiers, animal capacity vs occupancy, silo/stable/mill/greenhouse/obelisks, cellar & kitchen unlock status

chests

Every container: type (Chest/Stone/Big/special), map + tile, color, contents

find_item

Where is X? Searches backpacks, chests, machine outputs. Map + tile + color

net_worth

Gold + sellable value of everything held (from each item's own price)

Planning + completion

Tool

What

quests

Per-player quest journal + special-orders board (objectives + progress); item quests show requested item, on-hand count, and completable_now. research=True attaches a wiki how_to_obtain summary + infobox for each requested item

can_complete_now

CC bundles you could finish from what's in your chests right now

bundle_sourcing

Incomplete bundles + per missing-item wiki how-to-obtain + unlock-aware locked_source_hints (flags sources behind gated locations)

missing_museum

Undonated minerals + artifacts, with where they drop

collections

Collection tabs (multiplayer-aware, unioned across all farmers): fish caught (count + personal-record size), minerals/artifacts found — each checked against the SHARED farm museum (what the farm still needs). Fish are never donatable; only artifacts + minerals are

cooking

Cooking recipes known-but-not-made, with ingredients + on-hand count (cookable now). Kitchen access is farm-wide — anyone can cook if ANY house is upgraded (or they hold a Cookout Kit)

missing_recipes

Cooking/crafting recipes learned-but-not-made (+ how many not yet learned), per player

shipping_tracker

Items shipped by name + qty; distinct count vs the 154 Full-Shipment target

golden_walnuts

Ginger Island walnut progress: found vs 130, unspent, island-unlock + repeatable sources

secret_notes

Secret Notes found (1-25) with per-note found/missing flags

tailoring

Every item you've tailored at the sewing machine / Emily's (resolved to names)

raccoon

The 1.6 Raccoon storyline: requests completed, stage, times fed, current-request season

perfection

Real weighted Perfection %: 11 categories, each with have/total + earned %. 1.6-accurate (Farmer Level = player.Level/25) + per-player co-op breakdown

daily_briefing

Morning digest: luck, today/tomorrow weather, day-of-week + traveling cart (Fri/Sun), birthdays, festivals, open quests/special orders with due/days_left, machines/crops ready, pets due

gift_helper

Birthdays (from save) + your hearts + loved gifts, flags what you already hold

ready_to_collect

Machines with product ready (name, product, location + tile) + crops ready to harvest

fish_available

Fish catchable now (season/weather/time), only_uncaught filters

mods

Detect mods; list what couldn't map to vanilla (modded ids, unmapped bundle/museum)

Calculators (save + verified game formulas)

Tool

What

skill_xp_forecast

Actions to hit a target skill level (farming XP formula)

fishing_xp_forecast

Catches to a target fishing level (difficulty/perfect/treasure/legendary)

processing_planner

Kegs/jars to clear the crop backlog in N days + est. gross gold

processing_value

Raw vs wine/juice vs jelly/pickle for a crop (Tiller/Artisan/quality aware)

crop_planner

Crops that mature in the window + profit/tile (quality_weighted optional)

crop_quality_odds

Gold/silver/normal/iridium % from farming level + fertilizer + food buff

sprinkler_plan

Sprinklers + materials for N tiles, and whether your bars can build them

build_planner

Total materials to craft a set of machines (e.g. '20 Keg, 5 Tapper'), with bars rolled down to ore + coal + furnace-time and resin/syrup to tapper-nights, vs your inventory

fish_pond_forecast

Days to fill a pond to capacity + roe notes

friendship_forecast

Loved gifts + weeks to a target heart level

animal_product_quality

Iridium/gold/silver produce odds per animal (friendship + mood + prof)

animal_product_value

Raw (Rancher) vs processed (Artisan) value of milk/egg/wool

list_buffs

Food buffs that raise a skill level (Farmer's Lunch +3, Trout Soup +1)

Wiki verification

Tool

What

wiki_search

Search the Stardew Valley Wiki (titles + snippets)

wiki_page

A page (or one section) as clean text — to verify facts / pull context. Rough input (puffer fish, sturgeon) is auto-resolved to the right page

wiki_infobox

A page's infobox as structured fields (price/season/location). Auto-resolves rough input

wiki_category

Every page in a wiki category (e.g. Spring fish, Summer crops) — answer "all X in season Y" exhaustively. Case-insensitive (Summer Crops works) with near-match suggestions

how_to_obtain

Every way to get an item (drops, shops, trades, gifting) — the wiki lead summary + infobox source. Plan how to get a quest/bundle item. Auto-resolves rough input (bat wing, large goat milk)

villager_schedule

A villager's wiki schedule + your save's date/weather/hearts

Files

  • sdv_parser.py — the read-only save parser (ElementTree)

  • sdv_wiki.py — MediaWiki Action API client (api.php; the wiki's rest.php returns empty, so Action API it is), cached + rate-limited

  • sdv_calc.py — the calculators + reference tables

  • sdv_mcp_server.py — the 58 tools

Known limits

  • Vanilla + whatever the wiki documents only. Modded content lives on separate wikis.

  • missing_recipes lists recipes you've learned but not made; recipes not yet learned show only as a count (they aren't in the save). shipping_tracker lists what you've shipped by name — a by-name "still to ship" list isn't modelled (the save only stores what shipped), so its remaining count is approximate vs the 154-item set.

  • quests: completable_now covers item delivery/harvest/resource quests (you still hand the item in); monster/fishing/socialize quests report progress counters instead. Special-order objectives resolve their item (e.g. "Juice") and show due/days_left. days_left is omitted for untimed quests (billboard/fetch quests have no timer).

  • Item names come from a bundled catalog (sdv_items.py) generated from the game's unpacked assets, plus a fallback that resolves anything present in your save. Regenerate for a new game version with python scripts/gen_items.py.

  • Wiki tools need outbound network. The save tools don't.

Available Tools

49 tools
animal_product_qualityA

Iridium/gold/silver/normal produce odds per animal (friendship + mood + Coopmaster/Shepherd). Reads all save animals, or models one.

Inputs: mood, save_path, friendship, animal_type, +1 more. Returns: note, error, from_, result, +2 more

animal_product_valueC

Raw (Rancher +20% + quality) vs processed (Artisan +40%) value of an animal product.

Inputs: product (required), artisan, quality, rancher, +1 more. Returns: best, note, error, values, +4 more

buildingsA

Farm buildings and farmhouse upgrades: what's built (barns, coops, silo, stable, mill, greenhouse, obelisks, etc.) with animal-house tier and total animal capacity vs current occupancy, plus each player's house upgrade level (kitchen at 1, cellar at 3). Use this to reason about what to build/upgrade next and whether there's room for more animals or which house perks (cooking, cellar aging) are unlocked.

Inputs: save_path.

build_plannerA

Total materials to craft a set of machines, with bars rolled down to ore + coal + furnace-time and tapper products (Oak Resin, Maple Syrup, Pine Tar) rolled down to tapper-nights, then compared against the save's inventory (still_needed). Answers 'what do I need to build 20 kegs + 5 tappers, and how much ore/coal/furnace time?'

Inputs: spec (required), tappers, furnaces, save_path.

bundle_sourcingA

Incomplete Community Center bundles with, for each still-needed item, a wiki how-to-obtain summary AND reachability hints: if the summary references a gated location that isn't unlocked in this save (e.g. Desert, Ginger Island), it's flagged via locked_source_hints (a hint - the item may have an ungated source too). Includes the full unlocks snapshot.

Inputs: research, save_path, research_limit.

can_complete_nowC

Incomplete CC bundles finishable from items currently held (presence-only).

Inputs: save_path.

chestsB

Every container with identity + location: type (Chest/Stone Chest/Big Chest/ special), map + tile (X,Y), color label, item count, and full contents.

Inputs: save_path.

community_centerB

Community Center: rooms done/left, every incomplete bundle with exact items still required, and Vault payment status.

Inputs: save_path.

crop_plannerA

Which crops fully mature in the window and profit per tile. Tiller +10% auto-applied. Base prices unless quality_weighted.

Inputs: top, budget, season, days_left, +3 more. Returns: note, crops, budget, season, +4 more

crop_quality_oddsC

Gold/silver/normal (and iridium with Deluxe) crop-quality percentages.

Inputs: player, food_buff, save_path, fertilizer, +1 more. Returns: note, error, gold_pct, food_buff, +6 more

daily_briefingB

One-call morning digest from the save: date, daily luck, upcoming birthdays with the exact loved gift to give (from your inventory) or ideas to acquire + current hearts, open quests and active special orders with objectives/deadlines (the real tasks), festivals in the next 7 days, next_goals (closest progression wins: skills near a level/profession, nearest bundles, museum milestone and perfection categories), and the routine chores (machines, crops, animals to pet).

Inputs: save_path.

feedC

Animal feed status: animals, silo hay, fiber, and days of feed covered.

Inputs: save_path.

find_itemA

Locate an item across player backpacks, all chests, and machine outputs. Returns each place holding it with quantity and container location (map + tile + color) - answers 'where is my X?'.

Inputs: name (required), fuzzy, save_path.

fish_availableA

Fish catchable under given conditions (defaults to the save's current season, any weather). Each entry lists seasons, weather, locations, time, already-caught.

Inputs: season, weather, save_path, only_uncaught.

fishing_xp_forecastB

Catches needed to reach a target fishing level from save XP. XP = ((quality+1)*3) + (difficulty/3), x-multipliers stack (see note).

Inputs: target_level (required), fish, player, perfect, +5 more. Returns: fish, note, error, player, +13 more

fish_pond_forecastC

Days to fill a fish pond to capacity via reproduction.

Inputs: fish, capacity, save_path, spawn_days, +1 more. Returns: note, from_, ponds, forecast

friendship_forecastC

Loved gifts + weeks to reach a target heart level from current save points.

Inputs: villager (required), player, save_path, target_hearts, +1 more. Returns: note, error, known, player, +7 more

friendshipsB

Per-player villager hearts/points and spouse status.

Inputs: save_path.

full_reportC

Everything at once: overview, players, CC, inventory, processing, feed, museum, monster goals, friendships, perfection, tools, wallet, mods.

Inputs: save_path.

gift_helperA

Per-villager birthday (read from the save) + your current hearts + notable loved gifts, flagging which loved gifts you currently hold. Also lists birthdays within upcoming_days. Loved-gift lists are a curated summary - use wiki_page(villager) for the authoritative full list.

Inputs: save_path, upcoming_days.

golden_walnutsA

Golden Walnut progress on Ginger Island: found vs 130, unspent balance, whether the island is unlocked, and repeatable-source progress.

Inputs: save_path.

how_to_obtainA

How to get an item: the wiki's lead-section summary of every acquisition method (monster drops, shop purchases, trades, gifting, crafting) plus the structured infobox (source/season/price). Use this to plan the best way to obtain a quest/bundle item. Call wiki_page(item) for full drop-rate detail.

Inputs: item (required).

inventoryA

Items held: each player's backpack plus chest contents. Default merges all chests into one bag; set by_container=True for a per-container breakdown.

Inputs: full, save_path, by_container.

list_buffsA

Food/consumable buffs that raise a skill LEVEL (Farmer's Lunch +3, Trout Soup +1). These change level-dependent effects, NOT XP gain.

Inputs: skill.

machinesA

Inventory of every placed processing machine (Furnace, Keg, Cask, Seed Maker, Charcoal Kiln, Tapper, Bee House, Preserves Jar, etc.) grouped by type with counts and state (ready / working / idle). Excludes chests and decorative craftables. Use this to answer 'what/how many machines do I have'; machines_ready shows only machines with output ready to collect right now.

Inputs: save_path.

missing_museumA

Undonated museum items (minerals + artifacts) with sourcing notes.

Inputs: save_path.

missing_recipesA

Per player: cooking + crafting recipes you've LEARNED but not yet made (make these to progress Perfection), with known/made counts and how many you still haven't learned. Pairs with perfection Cooking/Crafting categories.

Inputs: save_path.

modsC

Detect mods and list what couldn't be mapped to vanilla references (modded item ids, unmapped bundle/museum entries).

Inputs: save_path.

monster_goalsB

Adventurer's Guild eradication goals: kills vs target + reward per category.

Inputs: save_path.

museumC

Museum donations out of 95 and the next milestone (e.g. 60 = Rusty Key).

Inputs: save_path.

net_worthA

Gold + sellable value of everything held (backpacks + chests + machine outputs), data-driven from each item's base sell price. Economy snapshot.

Inputs: save_path.

overviewB

Headline state: farm name, players, in-game date, shared money, lifetime earnings, deepest mine level, game version.

Inputs: save_path.

perfectionB

Full weighted Perfection %: the 11 in-game categories (shipped, obelisks, golden clock, monster slayer, great friends, skills, stardrops, cooking, crafting, fish, walnuts) with each one's have/total and earned %. Verified weights.

Inputs: save_path.

playersB

Every player: skill levels, XP, XP-to-next-level, professions, spouse, backpack size, house-upgrade level.

Inputs: save_path.

player_toolsB

Each player's tools (pickaxe/axe/hoe/watering can/rod) and upgrade tier.

Inputs: save_path.

processingA

Keg/jar planning data: held crops grouped into fruit/veg/special (by the save's own item category) + machine counts. Modded items are excluded and listed separately.

Inputs: save_path.

processing_plannerC

From held crops + machines owned: kegs/jars needed to clear the backlog in days and estimated gross gold (see note for multipliers/cycle-day caveats).

Inputs: days, artisan, save_path, extra_jars, +1 more. Returns: veg, days, note, fruit, +11 more

processing_valueA

Rank ways to sell a crop: raw (Tiller + quality) vs keg (wine/juice) vs jar (jelly/pickle). See note for multipliers.

Inputs: item (required), kind, artisan, quality, +2 more. Returns: best, item, kind, note, +7 more

questsA

Every player's active quest journal + the special-orders board. For item delivery/harvest/resource quests it names the requested item, counts how many are on hand (across all backpacks + chests), and flags completable_now when you already hold enough to turn in. Monster/fishing/socialize quests report progress counters. Set research=True to attach wiki guidance per quest.

Inputs: research, save_path, research_limit.

ready_to_collectB

What's ready right now: placed machines whose product is ready to collect (kegs/jars/mayo/cheese/tappers/mushroom boxes/crab pots) and crops ready to harvest in tilled soil.

Inputs: save_path.

shipping_trackerB

What the host has shipped (basicShipped) by name with lifetime quantities, plus distinct count vs the 154-item Full Shipment / perfection target.

Inputs: save_path.

skill_xp_forecastA

Actions needed to reach a target skill level from current save XP. Supply item_price (crop harvest) OR per_action_xp. Food buffs do NOT change XP.

Inputs: skill (required), target_level (required), player, save_path, +2 more. Returns: note, error, skill, action, +8 more

sprinkler_planC

Sprinklers + materials to water tiles, and whether the save's bars can build them.

Inputs: tiles (required), save_path, sprinkler. Returns: note, error, tiles, shortfall, +6 more

unlocksA

Which gated locations/vendors are reachable in THIS save (Desert + Desert Trader, Sewers/Krobus, Skull Cavern, Casino, Quarry, Greenhouse, Minecarts, Movie Theater, Adventurer's Guild, Ginger Island) with what each gates and, if locked, how to unlock it. Use this to filter item-acquisition advice to what's actually available (e.g. don't suggest the Desert Trader if the bus isn't fixed).

Inputs: save_path.

villager_scheduleA

A villager's daily schedule from the wiki, paired with YOUR save context (current date, weather, and hearts) so you can pick the matching conditional branch. Schedules depend on season/day/weather/hearts/events, so read the wiki text against the context provided.

Inputs: villager (required), save_path.

walletA

Special keys/items owned (Rusty Key, Skull Key, Club Card, etc.). Reads 1.6 mail flags + legacy booleans, so it's correct on 1.5 and 1.6 saves.

Inputs: save_path.

wiki_infoboxA

A page's infobox as structured key/value fields (price/season/location) - the most reliable surface for verification.

Inputs: title (required).

wiki_pageA

Fetch a wiki page as cleaned plain text - to VERIFY facts and pull context (prices, seasons, locations, event schedules).

Inputs: title (required), raw, section.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 49 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, covering specific aspects of the game like crops, animals, fishing, community center, etc. Even closely related tools like animal_product_quality and animal_product_value measure different metrics.

    Naming Consistency4/5

    Most tool names follow a descriptive noun_verb or verb_noun pattern (e.g., crop_planner, find_item), but some are single words (e.g., buildings, friends) without a verb, creating minor inconsistency.

    Tool Count2/5

    With 49 tools, the server is overly large for a typical MCP. While each tool serves a specific purpose, the set could be consolidated (e.g., combining related queries). This number exceeds the recommended range and may overwhelm agents.

    Completeness5/5

    The tool set covers nearly every facet of Stardew Valley—crops, animals, fishing, mining, community center, friendships, museum, perfection, and more. It includes planning, analysis, and lookup tools, leaving few gaps for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that serves live HayDay game data (crops, products, animals, machines, level unlocks) for AI agents to help plan your farm without interacting with the game itself.
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes the Stardew Valley Wiki as structured data via MCP tools for keyword/semantic search, page retrieval, and entity listings.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes RuneScape 3 data from the RuneMetrics, Grand Exchange, and RuneScape Wiki APIs, enabling natural language queries for player profiles, XP gains, quests, item prices, and wiki content.
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Read-only MCP server exposing one Muninn Minecraft backend's capabilities via safe, capability-aware tools. Broadly covers server status, CoreProtect lookups, Paper, CMI, and WorldGuard queries.
      MIT