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.”

• 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 What the AI can and cannot do.

• 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 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:

• 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.

1. Buy MadaoMCP and update MadaoCore from the MINION store.
2. Start FFXIV with FFXIVMinion as usual and log in. If the game was already running, press Reload.
3. 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.
4. 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.
5. Connect your AI app: Claude Code, Claude Desktop or another AI app.
6. Turn the game link on (next section).
7. Ask your AI: “What is my bot doing right now?”

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

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 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.

Run this once, in any terminal:

claude mcp add --scope user madao-llm -- "<LuaMods>\MadaoExe\MadaoLLM.exe"

--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 The MadaoLLM window). To remove it: claude mcp remove --scope user madao-llm.

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.

{
  "mcpServers": {
    "madao-llm": {
      "command": "<LuaMods>\\MadaoExe\\MadaoLLM.exe"
    }
  }
}

Then fully quit Claude Desktop from the system tray (closing the window is not enough) and start it again.

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.

• “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.”

• 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:

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.

• 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” 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 paused the Planner, MadaoLLM does not start or resume it.

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.

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.

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.

• 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.

• 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.

• 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.

• 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.

Other programs on your PC can check, start and stop the bot through the MadaoLLM that your AI app runs:

MadaoLLM.exe ctl status
MadaoLLM.exe ctl start --plan
MadaoLLM.exe ctl start --current
MadaoLLM.exe ctl stop

• 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.

• 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.

Look at the MadaoLLM: line in the MadaoLLM Bridge window first. A grey line under it says what to do.

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 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 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.

• “turn the Planner off in its window first”: the Planner runs, or 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.

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

Questions and bug reports: MadaoSupport Discord.