====== MadaoMCP ======
MadaoMCP lets the AI assistant you already use (Claude Desktop, Claude Code or any other MCP app) talk to your Madao bot.
Ask it what the bot is doing, tell it to start or stop, or let it make a new profile for you: a Planner schedule, or a gather, craft or fate profile.
The program that does this is called MadaoLLM (''MadaoLLM.exe''), so the windows and buttons below say MadaoLLM.

Examples of what you can type to your AI:
  * "What is my bot doing right now?"
  * "Make me a gathering profile that farms a lot of Rhalgr's Streak."
  * "Start my plan."
  * "Stop."

<WRAP important>MadaoLLM has two halves. The in-game half is the **MadaoLLM Bridge** window inside [[madaocore|MadaoCore]]. The other half is the small program ''MadaoLLM.exe'', which your AI app starts by itself. You need both.</WRAP>

===== Features =====
  * Tells you what the bot does: running or not, the mode, the Planner and its current plate, job, level, location and the latest bot messages.
  * Starts and stops the bot, or the Madao Planner, from your chat.
  * Builds Planner schedules and gather, craft and fate profiles, checks them and saves them for you.
  * Looks up recipes and gathering points in the game's own data.
  * Applies a profile that it made. It applies a profile that you made or downloaded only after you allow that in game.
  * Works with several characters at once.
  * Has its own window to watch and control your bots without any AI app.
  * Lets other programs on your PC (a Stream Deck button, Task Scheduler, your own script) check, start and stop the bot with one command.
  * Stays safe: it will not sell, discard or destroy your items, and it asks you before it acts. See [[madaomcp#what_the_ai_can_and_cannot_do|What the AI can and cannot do]].

===== Requirements =====
  * [[madaocore|MadaoCore]] (Free), up to date from the MINION store. The in-game half of MadaoLLM is part of MadaoCore.
  * MadaoMCP (10 EUR, MINION store) - this addon. The MadaoLLM program is given only to MadaoMCP owners, see [[madaomcp#get_madaollm|Get MadaoLLM]].
  * An AI app that supports MCP: Claude Desktop, Claude Code, Codex, Cursor and others. You need your own account for it.
  * Windows. The MadaoLLM window also needs Microsoft's "WebView2 Runtime". Windows 11 and an up-to-date Microsoft Edge already have it. Your AI app does not need it.
  * Your AI can make every kind of profile. To run one, you need the addon for that kind:

^ Profile your AI makes ^ Needed to run it ^
| Planner schedule (the Madao Planner) | [[madao_plus|Madao Plus]] (or the older MadaoCorePlus2) |
| Gather profile | [[madao_gather|Madao Gather]] |
| Craft profile | [[madao_craft|Madao Craft]] |
| Fate profile | [[madaofate|MadaoFate]] |

===== Get MadaoLLM =====
  * Buy MadaoMCP in the MINION store.
  * MadaoCore then installs MadaoLLM for you with the other Madao Tools: while the bot is stopped and your character is in the world, it downloads ''MadaoLLM.exe'' into ''LuaMods\MadaoExe''. **Install MadaoTools (EXE)** in the MadaoCore window starts it at once; **Update MadaoTools (EXE)** shows when a new version is out.
  * Update MadaoCore from the MINION store first. Old MadaoCore versions have no bridge and no **MadaoLLM Bridge** menu entry.

===== How to start =====
==== Install ====
  - Buy MadaoMCP and update MadaoCore from the MINION store.
  - Start FFXIV with FFXIVMinion as usual and log in. If the game was already running, press **Reload**.
  - Keep the bot stopped for a minute: MadaoCore installs the Madao Tools by itself, or press **Install MadaoTools (EXE)**. ''MadaoLLM.exe'' is then in ''LuaMods\MadaoExe''.
  - In that **MadaoExe** folder, make a text file named ''madao_llm.toml'' and this one line, with the full path of your **LuaMods** folder between the single quotes: ''luamods_dir = '<LuaMods>' ''. This tells MadaoLLM where your game folder is.
  - Connect your AI app: [[madaomcp#claude_code|Claude Code]], [[madaomcp#claude_desktop|Claude Desktop]] or [[madaomcp#other_ai_apps|another AI app]].
  - Turn the game link on (next section).
  - Ask your AI: "What is my bot doing right now?"

In the steps below, ''<LuaMods>'' means the full path of your LuaMods folder.

==== Turn the game link on ====
MadaoLLM does nothing until you turn it on in game. Only you can do this, in one of two ways:
  * Click the MadaoLLM icon in the Madao main window (**Utilities Link** row). This is the one-click way and it opens the MadaoLLM window too.
  * Or open the FFXIVMinion menu, click **MadaoLLM Bridge**, then press **Enable**.

While the link is on, your AI and programs on your PC that use ''MadaoLLM.exe ctl'' can read the bot's status and start and stop it.
One switch covers every game client you have open. Press **Disable** when you are done.
Your own profiles stay off until you allow them (see [[madaomcp#your_own_profiles|Your own profiles]]).

The **MadaoLLM Bridge** window has a **MadaoLLM:** line. It should say **connected (port N)** within about 20 seconds.
First it may say **connecting to MadaoLLM** and then **reaching MadaoLLM (waiting for its first answer)**. That is normal: do not restart anything.

==== Claude Code ====
Run this once, in any terminal:
<code>
claude mcp add --scope user madao-llm -- "<LuaMods>\MadaoExe\MadaoLLM.exe"
</code>
''%%--scope user%%'' makes MadaoLLM available in every folder you start Claude Code in.
Or skip the terminal: open the MadaoLLM window, go to the **MCP** page and press **Start Claude** (see [[madaomcp#the_madaollm_window|The MadaoLLM window]]).
To remove it: ''%%claude mcp remove --scope user madao-llm%%''.

==== Claude Desktop ====
Put this entry into ''%APPDATA%\Claude\claude_desktop_config.json'' (Claude Desktop: **Settings**, **Developer**, **Edit Config** opens it). Write each backslash twice in JSON. If the file already has an ''mcpServers'' block, add only the ''madao-llm'' part to it.
<code>
{
  "mcpServers": {
    "madao-llm": {
      "command": "<LuaMods>\\MadaoExe\\MadaoLLM.exe"
    }
  }
}
</code>
Then fully quit Claude Desktop from the system tray (closing the window is not enough) and start it again.

==== Other AI apps ====
Add the same JSON entry as above to your app's MCP settings. For Codex, use the **MCP** page of the MadaoLLM window.
If you do not want to keep ''madao_llm.toml'', set the environment variable ''MADAO_LUAMODS_DIR'' to your LuaMods folder instead.

==== Good first things to try ====
  * "What is my bot doing right now?"
  * "Is the Planner running? Which plate is it on?"
  * "Which profiles do I have?"
  * "Which modes can you choose from?"
  * "Choose Repair mode and start it."
  * "Make a gathering profile, then apply it."
  * "Stop." and later "Resume my plan."

===== What the AI can and cannot do =====
==== The AI can ====
  * Tell you what each bot does (status, mode, Planner, plate, recent messages).
  * Make profiles, check them and write them into your MadaoFiles folder: Planner (schedule), gather, craft and fate.
  * Look up recipes and gathering points, so it never has to guess an id.
  * List your profiles, apply a profile that MadaoLLM made, and read it back so it can change it.
  * Apply a profile you made or downloaded yourself, but only after you allow that in game and only when you ask for that profile.
  * Choose the mode that the MadaoCore window runs, from a safe list, and read the Planner's schedule: its plates, which one runs and when the next is due.
  * Read the settings of Allied Society, Beastmaster, Duty Support and Custom Delivery and, after you agree, change them. It can also turn plain steps into a Planner schedule.
  * Start and stop the bot. Starting always names one target:

^ Target ^ What it starts ^
| plan | The Madao Planner, or resumes it after a stop |
| current | The mode selected in the MadaoCore window |

Only these modes can be started with **current**: Leve, Gather, Craft, Fate, Retainer, Ocean Fishing, Repair, Allied Society, Craft Trial, Beastmaster, Duty Support and Custom Delivery.
Stop is never refused. It also stops the stock FFXIVMinion bot if that is running.

==== The AI cannot ====
  * Choose a mode outside the safe list (selling, discarding, desynthesis, materia, trading).
  * Sell, discard, desynth or otherwise use up your items.
  * Start a plan with a step that is not on the safe list: character swap or login, Lua code, purchases, turn-ins and exchanges, and similar. The answer names the step. Start such a plan from the Planner window yourself.
  * Make or start a craft profile that spends or gives away things by itself: buying from the Market Board, turning in collectables and spending the scrips, or handing items to the Free Company workshop. Switch those on in game and start that profile from its window yourself.
  * Start Beastmaster while its item-discarding options are on, or start Duty Support from a profile file. It runs one picked duty only.
  * Apply a profile you made or downloaded yourself until you allow that in game.
  * Drive the modes of the stock FFXIVMinion bot.
  * Turn the game link on. Only you can, in game.

The bridge in MadaoCore knows a fixed list of commands. Replacing or editing ''MadaoLLM.exe'' cannot add a command or unlock anything the bridge refuses.
Profiles are the one thing that does not go through that list: MadaoLLM writes the file and the bot then does what the file says.
So every profile is checked before it is written (no Lua code, only safe plate types), an old file is copied to a backup folder before it is replaced, and MadaoCore checks the selected plan or profile against the safe list before it starts.
Still, install MadaoLLM only from a source you trust, and treat a profile file from a stranger like any other file from a stranger.

===== Plan mode (the Madao Planner) =====
"Plan" means the Madao Planner: the schedule that runs your plates one after another.
  * "Stop" while the Planner runs **pauses** it. The bot stops where it is and nothing from your profiles runs. The answer says whether your AI can resume it. If not, use the Planner window.
  * "Start" with target plan **resumes** the same plate. The paused time does not count against the plate's time limit.
  * When the Planner is off, "start" with target plan starts the schedule that is selected in the Planner window.
  * While the Planner runs, choosing a mode, starting the current mode and applying a profile are refused. Ask your AI to stop first: that pauses the Planner.
  * While MadaoLLM has the Planner paused, your AI can work by hand. It can choose a mode and start it, and the Planner stays paused. To go back, stop the manual run, then start with target plan.
  * Applying a schedule ends the pause and turns the Planner off. The next start with target plan begins that schedule at its first plate.
  * The **Stop** button in the Planner window also ends a MadaoLLM pause: it turns the Planner off and counts the current plate as done.
  * During a character swap that it cannot resume, "stop" does not pause the Planner, because that would leave the game on the title or character select screen. The swap finishes and the plate starts. Say "stop" again once your character is in the world.
  * A pause does not survive an in-game **Reload**. If the Planner's auto start is on, a Reload starts it again.
  * If [[madaomultibox|MadaoMultiBox]] paused the Planner, MadaoLLM does not start or resume it.

===== Your own profiles =====
Your AI can apply two kinds of profile. The rules differ.
  * **Profiles that MadaoLLM wrote.** MadaoLLM remembers a fingerprint of every profile it writes and refuses a file that does not match: one from somewhere else, or one that changed after it wrote it. Your AI can read these back and change them. A profile you make or save in the MadaoLLM window counts as one MadaoLLM wrote, with everything you typed into it.
  * **Profiles you made or downloaded yourself.** Your AI can apply one only after you allow it and only when you asked for that profile. It is off until you allow it.

To allow it, open the **MadaoLLM Bridge** window in game while the link is on and press **Allow my own profiles too**.
Or tick **Also let it apply profiles I made or downloaded myself** before you press **Enable**. **Stop applying my own profiles** takes it back. **Disable** turns off the whole link.

What MadaoLLM does with one of your own profiles:
  * It reads the file, and every profile it uses, as plain data without running it. The bot checks it again.
  * It refuses a profile that is not plain data, that names a file or folder on your PC, or that changed after your AI looked at it. Then nothing is changed.
  * A skill list that runs its own Lua code (gather and craft skill lists can) still works, but the answer carries a warning that names the list, and your AI passes it on to you. A skill profile of the stock FFXIVMinion skill manager is refused.
  * What is inside your own profiles is never sent to your AI app. Your AI sees only the file names, a check number for each file and, when MadaoLLM refuses or warns, which field or skill list is the reason.
  * This is not proof that a profile is safe: the game runs profile files as programs. Keep only profiles you trust in your profile folders.

You can also select a profile yourself in game (the MadaoCore window or the Planner window) and then ask your AI to start. That needs no permission. The safe-list check still applies.

===== Several characters =====
You can run more than one game client. Your AI lists them and asks you which character you mean.
Starting, choosing a mode and applying a profile act on one character at a time. Your AI never picks one by itself.
**Stop** without a character name stops every connected game client, so your AI says so before it does it.

===== The MadaoLLM window =====
MadaoLLM has a window of its own, so you can watch and control your bots without an AI app.
Open it from the MadaoLLM icon in the Madao main window, or run ''MadaoLLM.exe ui'' (for example from a desktop shortcut you make yourself). The icon works once your AI app has started MadaoLLM one time.

The icon click also turns the game link on, like **Enable** does, for every game client you have open. Your own profiles stay off. The icon's tooltip says all this.
To turn the link off, press **Disable** in game, or press **Turn the game link off** on the **Settings** page of the window (it asks first). Only the game can turn the link on: the window, your AI and ''MadaoLLM.exe ctl'' cannot.

  * **Characters** page: for every running game client it shows the character, world, job, location, HP, the mode, the Planner and its plate, what the bot does right now, the last error and the latest bot messages.
  * You can start and stop the bot, pause and resume the Planner, and choose a mode from the safe list. Buttons: **Start Planner**, **Start current mode**, **Stop**, **Stop all**, **Resume**.
{{::madaomcp_window_characters.png?600|}}
  * **Profiles** page: make, check, save and apply Planner schedules and craft, gather and fate profiles in forms (**New profile**). Your own profiles are listed too: **View** shows one read-only, and **Apply** uses it for one of your characters once you allowed your own profiles in game. It asks first and shows any skill-list warning. Changing your own profile still needs the game's own editor.
{{::madaomcp_window_profiles.png?600|}}
  * **MCP** page: connects Claude Code and Codex to MadaoLLM for you. See below.
  * **Settings** page: how often each part refreshes, the language, light or dark theme, and **Turn the game link off**.

The window follows the same rules as your AI: the same safe list and the same checks before anything starts.
The window and your AI app can be open at the same time. They share one connection to the game. Keep every copy of ''MadaoLLM.exe'' on the same version.

==== The MCP page ====
{{::madaomcp_window_mcp.png?600|}}
  * It opens in a simple form. Press **Start Claude** or **Start Codex**. MadaoLLM prepares the folder ''Documents\MadaoLLM-AI'' (the MadaoLLM tools, their guides and the rules your AI follows, in the window's language) and opens the app there. It changes nothing outside that folder.
  * The first time, the app asks you to sign in and whether you trust the folder. Answer yes. Claude Code or Codex must be installed, and each needs its own account or subscription.
  * Tick **Advanced setup** for more. **Set up locally** writes the setup into one project folder of your choice (not inside the game's folders). **Set up globally** adds MadaoLLM to the app's own settings for every folder, and asks first.
  * Both write the MadaoLLM rules (look first, ask before it starts, stops or applies anything) into ''CLAUDE.md'' or ''AGENTS.md'' between two MadaoLLM marker lines. Your other text is kept, and a copy of every file it changes is saved first.
  * The page can also install the MadaoLLM plugin for Claude Code and Codex. It adds skills that teach the AI to use the MadaoLLM tools safely. MadaoLLM makes the plugin on your PC; nothing is downloaded. Install, Update and Remove each ask first.
  * The page also opens a console inside the window that starts Claude Code or Codex. Closing MadaoLLM ends the console and everything started in it.

==== Language ====
{{::madaomcp_window_settings.png?600|}}
  * The window can show English, Japanese, German, French, Simplified Chinese and Korean.
  * It starts in the language of your game client, else the display language of Windows, else English. Change it under **Settings**, **Language**.
  * English is built in. The other languages come with MadaoCore: update MadaoCore from the MINION store to get new or corrected ones. They are drafts that no native speaker has checked yet.
  * Messages from MadaoLLM and from the game stay in English, under a hint in your language. Your AI app always gets English answers.

===== Control from other programs =====
Other programs on your PC can check, start and stop the bot through the MadaoLLM that your AI app runs:
<code>
MadaoLLM.exe ctl status
MadaoLLM.exe ctl start --plan
MadaoLLM.exe ctl start --current
MadaoLLM.exe ctl stop
</code>
  * Use ''<LuaMods>\MadaoExe\MadaoLLM.exe'', with its full path.
  * ''%%--instance NAME%%'' picks one character (a character name, or an id that ''ctl status'' shows). **start** needs it when more than one game client is connected. ''%%--json%%'' prints the whole answer as JSON.
  * **start** and **stop** do exactly what your AI's start and stop do, with the same checks and refusals. **stop** without ''%%--instance%%'' reaches every connected game client.
  * It works only while your AI app is open and running MadaoLLM. ''ctl'' does not start a MadaoLLM of its own. The game link must be on.

^ Exit code ^ Meaning ^
| 0 | Done |
| 1 | Failed: no game client answered, it took too long, or the command line was wrong. The reason is printed |
| 2 | Refused. The reason is printed |
| 3 | No running MadaoLLM found: open your AI app |
| 4 | The game link is off: click the MadaoLLM icon in the MadaoCore window, or press **Enable** in the **MadaoLLM Bridge** window |

===== Please Note =====
  * **Privacy.** ''MadaoLLM.exe'' itself sends nothing over the internet. It opens one connection on your own PC only (address 127.0.0.1, a port from 41780 to 41789). A random key makes sure only MadaoCore's bridge can use it.
  * Your AI app is a different matter. Everything MadaoLLM answers (your character name, job, level, location, game language, what the bot does, recent bot messages, the profiles it reads and writes) becomes part of your chat. Your AI app sends it to your AI provider, like anything else you type there.
  * Folder paths in the answers are shortened: your FFXIVMinion install shows its last two folder names only, a path in your Windows user folder starts with ''~'', and your Windows account name is hidden in paths. If you do not want any of this, leave the game link off.
  * The MadaoLLM window is not an AI app. It sends nothing to anyone and loads nothing from the internet. Text you type into its profile editor is different once you save it: your AI can read that profile back. Do not put private notes in its text fields.
  * The game link works only while you are in the game world. On the title screen, the character select screen and loading screens it pauses and resumes by itself.
  * The program is not code-signed, so Windows may say "unknown publisher". Choose **More info**, then **Run anyway**.
  * Some activities spend gil or currency to do their job (Beastmaster buys gear, Custom Delivery buys materials and spends scrips). Your AI tells you before it starts them.
  * Keep every copy of ''MadaoLLM.exe'' on the same version, and keep MadaoCore up to date. A panel that needs a newer MadaoCore says "update MadaoCore from the store" and stays empty. The rest of the window still works.

===== Troubleshooting =====
==== The MadaoLLM: line ====
Look at the **MadaoLLM:** line in the **MadaoLLM Bridge** window first. A grey line under it says what to do.
^ It says ^ What to do ^
| disabled | Click the MadaoLLM icon in the MadaoCore window, or press **Enable**. |
| connecting to MadaoLLM | You just turned the link on. Wait a few seconds. |
| connected (port N) | All good. |
| reaching MadaoLLM (waiting for its first answer) | MadaoLLM holds the connection. Give it up to 20 seconds. Do not restart anything. |
| MadaoLLM not running | Nothing answers. Open or restart your AI app: it starts MadaoLLM. The bridge retries by itself. |
| token rejected %%--%% restart MadaoLLM | Restart your AI app. If it still says so after about 10 seconds, press **Disable**, then **Enable**. |
| version mismatch %%--%% update both | Read the grey line. Usually MadaoCore and ''MadaoLLM.exe'' are from different releases: update MadaoCore from the MINION store and press **Reload**. MadaoCore then updates MadaoLLM with the other Madao Tools. |
| MadaoLLM refused the exchange | Read the grey line. If it keeps happening, press **Disable**, then **Enable**. |

==== Common problems ====
^ Problem ^ What to do ^
| "the in-game LLM Bridge is off" | Click the MadaoLLM icon in the MadaoCore window, or press **Enable** in the **MadaoLLM Bridge** window. |
| "madao_llm.toml was not found next to MadaoLLM.exe" | Make the ''madao_llm.toml'' file in ''<LuaMods>\MadaoExe'' (see [[madaomcp#install|Install]]), then restart your AI app. |
| "no running game client is answering" | Check that FFXIV and FFXIVMinion run and you are logged in. Right after a **Reload**, answers can take about ten seconds. |
| "An older MadaoLLM is still running and holds the game link" | An older ''MadaoLLM.exe'' is still open, usually started by another AI app. Close that AI app, then restart this one. |
| "MadaoLLM could not open a local connection ... ports 41780 to 41789" | Something on your PC uses or blocks all those ports. Close programs that might use them, allow ''MadaoLLM.exe'' through your firewall, then restart your AI app. |
| No **MadaoLLM Bridge** in the FFXIVMinion menu | Your MadaoCore is older than MadaoLLM. Update MadaoCore from the MINION store, then press **Reload** or restart the client. |
| The menu says **MadaoLLM Bridge (built-in)** | An old MadaoLLMBridge add-on from a test version is still loaded, so the bridge stays off. Ask in the Discord below. |
| "the command was handed to the game client but no answer came back" | It may still have run. Ask your AI for the bot's status before you repeat a start or a stop. |
| Your AI shows no MadaoLLM tools | Fully quit Claude Desktop from the tray and start it again. Check the path in your ''madao-llm'' entry: it must point at ''MadaoLLM.exe'' in ''<LuaMods>\MadaoExe'', with each backslash written twice. For Claude Code, remove the entry and add it again. |
| The window does not open, or says WebView2 is missing | Install Microsoft's "WebView2 Runtime" (on Windows 10: the "Evergreen Standalone Installer"), then open the window again. |
| The window says "Reconnecting..." | The MadaoLLM that held the connection closed and another one takes over. Wait a few seconds. If it stays, press **Disable**, then **Enable** in game. |
| A panel says "update MadaoCore from the store" | Your MadaoCore is older than MadaoLLM. Update it, then press **Reload**. |

==== Start is refused ====
The answer says why. The usual reasons:
  * The Planner is running and you asked for the current mode (or to choose one). Ask your AI to stop first, or turn the Planner off in its window.
  * [[madaomultibox|MadaoMultiBox]] paused the Planner. MadaoLLM leaves it alone: resume it from MadaoMultiBox.
  * A plan step or a profile setting is not on the safe list. Start that plan or mode from its own window yourself.
  * The selected mode is not one of the modes listed in [[madaomcp#what_the_ai_can_and_cannot_do|What the AI can and cannot do]]. Choose one of them.
  * The MadaoCore window is on the Task Manager tab or the Leveler tab. Switch to another tab.
  * The bot already runs something (MadaoCore or the stock FFXIVMinion bot), or another MadaoCore feature holds the character. Ask your AI to stop first: stop covers all of these.
  * You are not logged in, you are dead, or the game is loading. Wait and try again.

==== Applying a profile is refused ====
  * "turn the Planner off in its window first": the Planner runs, or [[madaomultibox|MadaoMultiBox]] paused it. If it runs, ask your AI to stop first. That pauses the Planner and allows the apply. If MadaoMultiBox paused it, turn the Planner off in its window, apply, then start again.
  * The profile was not made by MadaoLLM, or it changed after MadaoLLM wrote it: if you asked for that profile, your AI can apply it as one of your own. Or select it in game yourself.
  * "The user has not allowed MadaoLLM to apply their own profiles": press **Allow my own profiles too** in the **MadaoLLM Bridge** window.
  * The answer says the profile names a file or folder on your PC, is not plain data, or changed since it was listed: nothing was changed. Fix it in the game's own editor, or select the profile in game yourself. After "changed since it was listed", your AI only needs to read the profile list again.

==== Uninstall ====
  - Press **Disable** in game, or press **Turn the game link off** in the MadaoLLM window.
  - Remove the **madao-llm** entry from ''%APPDATA%\Claude\claude_desktop_config.json'' (Claude Code: ''%%claude mcp remove --scope user madao-llm%%'').
  - MadaoCore keeps ''MadaoLLM.exe'' with the other Madao Tools. It does nothing while no AI app starts it and the game link is off.
  - The folder ''LuaMods\MadaoLLMBridge'' now holds only data, including copies of profiles that were replaced. You may delete it too.

===== Support and Feedback =====
Questions and bug reports: [[https://discord.gg/pJPhQDTjwT|MadaoSupport Discord]].