Patchwork
Patchwork provides a versioned MCP workspace for inspecting and safely editing the structure of closed FileMaker .fmp12 files, not record data.
Open a closed file as a working copy with
patchwork_open, using a Full Access account and password fromPATCHWORK_PASSWORD.Inspect the workspace:
patchwork_status,patchwork_log,patchwork_list,patchwork_show,patchwork_palette, andpatchwork_uses.Add fields (plain, global, or calculation), value lists, custom functions, and scripts.
Rewrite or append script steps as FileMaker text or
<Step>XML.Place existing fields on layouts with copied styling and labels.
Replace whole layouts, themes, value lists, or custom functions with edited XML.
Restyle themes and layouts: change colors, fonts, theme names, or swap a field across layouts.
Delete scripts, layouts, value lists, custom functions, or fields, with reference warnings and optional forced deletion.
Apply hand-written FMUpgradeTool patches as a last-resort operation.
Undo versions one at a time and save the current version to a new
.fmp12file.Use
dry_runon edits to write patches without applying them, and rely on post-change re-export checks to reject silently skipped changes.
Provides integration with Claris FileMaker, enabling AI agents to inspect and modify .fmp12 files by adding, editing, and deleting fields, scripts, value lists, custom functions, layouts, and themes. Changes are applied through Claris command-line tools, verified by re-exporting the file, versioned for undo, and made on a working copy so the original file is preserved.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Patchwork Add a Status field to the Clients table in Invoice.fmp12."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Quick start · Examples · Connect your agent · What it can change · Field guide · Français
Friday, 4 PM. A client asks for "just one more field" on the detail layout. You know the drill: define the field, copy the label, nudge every object below it, stretch the part… then do it all again on the next layout.
Patchwork lets your AI agent do those clicks for you. Just ask, in your own words, the way you would ask a colleague. Your agent adds the field and places it right where you said, writes scripts, creates value lists and restyles layouts, in a real
.fmp12file. Every change is checked, every change can be undone, and your original file is never touched.
Free and open source. Works with Claude Code, Cursor, Codex and Antigravity.
Requirements
Python 3.10 or later, on Windows, macOS or Linux.
The Claris command-line tools FMUpgradeTool and FMDeveloperTool. They come with the FileMaker Server installer (the free trial works), and no server has to run: install the Claris tools. Verified with FileMaker 2026 (26.0.3).
A closed
.fmp12and a Full Access account.
Related MCP server: Readedit
Quick start
Three commands, then you just talk to your agent.
pip install filemaker-patchwork
patchwork doctor # finds the Claris command-line tools
patchwork init . # wires this folder for Claude Code, Cursor, Codex and AntigravityNo install with uv: uvx filemaker-patchwork doctor, and uvx filemaker-patchwork mcp as the MCP server command.
Then ask your agent: "Open Invoice.fmp12 and add a Status field to Clients." That's it.
Good to know
It changes structure, not records. Fields, scripts, layouts, value lists, themes. For your data, use the Data API or OData.
It works on closed files, not hosted ones. Edit a copy, test it, then deploy it as you usually do.
It needs the Claris command-line tools (FMUpgradeTool and FMDeveloperTool). They come with the FileMaker Server installer, the free trial works, and no server has to run: install the Claris tools. Patchwork itself has no other dependency.
See it in action
Four real sessions on the free Claris Invoice solution. For each one: what was asked, what the agent did, and the file before and after. No mockups.
How it works
Why can't your agent just do this on its own? A FileMaker file is a binary file, and its structure hides behind dialogs an agent cannot click. Claris does ship a command-line way in, FMUpgradeTool, but it is picky: every object is addressed by a UUID, and a patch that is slightly wrong is silently skipped, while the tool still prints Patch File Applied.
Patchwork is the careful assistant in between:
🧵 Writes the patch | Reads the file's XML export and builds a patch with the right UUIDs, ids and catalog structure, so your agent doesn't have to |
🔍 Checks the result | Re-exports the file after every change and compares it with the previous version. If FileMaker skipped something, the change is refused, not silently lost |
🧭 Warns before breaking | Before a delete, it lists the scripts, layouts and calculations that use the object, and waits for your OK |
🕐 Keeps every version | Each change is a numbered version with its diff. Changed your mind? |
🔒 Protects the original | Everything happens on a working copy. |
More in how it works.
Connect your agent
One command sets everything up. Run patchwork init . in your project folder, new or existing: it adds the rules, the skills and the MCP configuration for every agent, and keeps the files you already have.
Agent | Configuration written by | Then |
Claude Code |
| Run |
Cursor |
| Enable |
⌨️ Codex |
| Trust the project when Codex asks |
Antigravity |
| Open the folder as a workspace |
Every agent gets the same 21 tools through patchwork mcp, a stdio MCP server. Your file's password stays yours: set it once in your shell with PATCHWORK_PASSWORD, and agents never see it. Manual setup: AI agents. Every tool, its parameters, answers and errors: MCP tools reference.
What it can change
Fields, plain-text scripts, value lists, colors and fonts, even a full rebrand. Every operation below was tried on real files and confirmed by re-exporting them.
Add | Edit | Delete | |
Fields · text, number, date, time, timestamp, container, calculation, global | ✅ | ✅ | |
Scripts, read and written as FileMaker text | ✅ | ✅ | ✅ |
Value lists | ✅ | ✅ | ✅ |
Custom functions | ✅ | ✅ | ✅ |
Layouts · place a field with its label, whole layout, colors, fonts, swap a field | ✅ field | ✅ | ✅ |
Themes · colors, fonts, name | ✅ | ||
Tables, table occurrences | 👁 read |
Scripts read and write the way the Script Workspace shows them, one step per line:Set Field [ Clients::Status ; "Gold" ]. Edit the text of patchwork show script NAME and send it back with set-steps: untouched lines keep their exact step, and every step is re-read after the change, so a dropped parameter is caught.
What FMUpgradeTool cannot do (record data, a brand-new theme, a single layout object on its own) is listed in the field guide.
Use it without an agent
Prefer the terminal? Everything the agent does is a plain command you can run yourself:
export PATCHWORK_PASSWORD='...' # Windows: $env:PATCHWORK_PASSWORD = '...'
patchwork open "Invoice.fmp12" --account Admin # working copy, version v000 (--no-password if the account has none)
patchwork add-field Clients "Loyalty Tier"
patchwork add-value-list "Loyalty Tiers" Bronze Silver Gold
patchwork log # every version and what changed
patchwork undo
patchwork save "Invoice v2.fmp12"Command | What it does |
| Starts a working copy in |
| Current version, and every version with what changed |
| Lists layouts, scripts, value lists, custom functions, themes, tables, fields |
| Prints a script as FileMaker text ( |
| Colors a theme uses, most frequent first |
| Adds a field: |
| Adds a custom value list |
| Adds a custom function, with |
| Creates a script from FileMaker script text (or |
| Rewrites a script with edited text from |
| Puts a field on a layout below another one, with a copy of its look and label. |
| Adds a value list or a custom function from XML |
| Replaces an object with your edited version of |
| Lists what references an object, and where its name appears in calculations |
| Deletes a script, layout, value list, custom function or field. Refused while other objects reference it, unless |
| Rewrites colors and fonts of a theme, or of the layouts' local styles |
| Applies a hand-written FMUpgradeTool patch, with the same checks |
| Drops the last version |
| Writes the current version to a new |
| One shot: colors, fonts, logo and theme name on a whole solution |
| The MCP server for agents |
| Wires a folder for Claude Code, Cursor, Codex and Antigravity |
| Shows which Claris tools Patchwork found. Exit code 2 if one is missing |
| Runs one Claris tool directly, file to file, with the same path checks |
Every editing command takes -m "note" for the log and --dry-run to write the patch without applying it. -C DIR, before the command, picks the project folder: patchwork -C ~/crm status. Without it, Patchwork uses PATCHWORK_PROJECT, then the nearest .patchwork/ from the current folder upward. open is the exception: it creates .patchwork/ in the -C folder, else in the current folder. patchwork COMMAND --help lists every option. More in examples and recipes.
Environment variables
Patchwork reads these from the environment. It never loads a .env file: set them in your shell or in the env block of your MCP client. .env.example lists them.
Variable | Used for |
| Password of the account given to |
| Encryption key, for files with encryption at rest. Passed to FMUpgradeTool when a patch is validated or applied, not when the file is copied or exported. Never printed. A full session on an encrypted file is to be confirmed |
| Project folder holding |
| Paths of the Claris tools, when |
|
|
| Seconds before a Claris tool that does not answer is stopped. Default 1800. Not in release 0.1.0 |
| Tests only: a copy of the Claris Invoice solution for the end-to-end tests |
Run from source and test
git clone https://github.com/Abdeltoto/patchwork-filemaker-mcp
cd patchwork-filemaker-mcp
python -m venv .venv
. .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e ".[image]"
python -m unittest discover -s testsThe unit tests need neither FileMaker nor the Claris tools. The end-to-end tests, lint and coverage checks are in CONTRIBUTING.md.
Repository layout
src/patchwork/ the package: CLI, MCP server, FileMaker logic
skills/, templates/ what `patchwork init` copies into a project
tests/ unit tests, fixtures/ (fictional exports), test_integration.py (real files)
docs/ guides, MCP tools reference, decisions/
examples/ recipes and the Maple & Oak brand
scripts/ extract-fms-tools.ps1 (Claris tools from the .msi, Windows)
brand.schema.json JSON schema of brand.json
server.json entry for the MCP registryHow the modules fit together: ARCHITECTURE.md.
The FMUpgradeTool field guide
The field guide collects every trap FMUpgradeTool sets without telling you, found the hard way on real files. Useful even if you never use Patchwork. A taste:
without
--generateGUIDs, theme and field patches are skipped;a layout's UUID is not the first
<UUID>inside it;replacing one layout object is skipped, replacing the whole layout works;
deleting a script step needs a
ScriptReferenceinside eachScriptStepReference.
Found another one? Add it.
FAQ
Contributing
Found a new FMUpgradeTool trap, wrote a recipe, or want a new operation? Everything is welcome: start with CONTRIBUTING.md. And if Patchwork gives you your Friday afternoon back, a ⭐ helps other FileMaker developers find it.
License
MIT. Patchwork is a community project, not affiliated with or endorsed by Claris International Inc. FileMaker and Claris are trademarks of Claris International Inc. Other product names and logos belong to their owners.
Available Tools
21 toolspatchwork_add_custom_functionAdd a custom function to the fileA
Create a custom function from a formula and its parameter names. The version is dropped with an error if FileMaker rejected the formula or stored other parameters. To change an existing function, read it with patchwork_show and send it back with patchwork_replace. Makes a new version; patchwork_undo reverses it.
Inputs: calc (required), name (required), params, dry_run, +1 more.
patchwork_add_fieldAdd a field to a table of the fileA
Add a field to a table. With calc the field is a calculation, otherwise a plain field of the given type. Refused when the field already exists. The result is re-exported, and the version is dropped with an error if the field is missing from it. The field is not put on any layout: use patchwork_place_field for that. Makes a new version; patchwork_undo reverses it.
Inputs: name (required), table (required), calc, type, +5 more.
patchwork_add_scriptCreate a new script in the fileA
Create a new script, empty when steps is omitted. Each step is re-read after the change, and the version is dropped with an error if one came back different. To change a script that exists, use patchwork_set_steps or patchwork_append_steps. Text is understood for: # (comment), Allow User Abort, Beep, Close Window, Commit Records/Requests, Delete Record/Request, Else, Else If, End If, End Loop, Exit Loop If, Exit Script, Freeze Window, Go to Layout, Halt Script, If, Loop, New Record/Request, Perform Script, Refresh Window, Set Error Capture, Set Field, Set Variable, Show All Records, Show Custom Dialog. For any other step, get a model with patchwork_show kind=step and send XML. Makes a new version; patchwork_undo reverses it.
Inputs: name (required), steps, dry_run, message.
patchwork_add_value_listAdd a custom value list to the fileA
Create a custom value list from a fixed list of values. The stored values are re-read, and the version is dropped with an error if FileMaker kept different ones. To change an existing value list, read it with patchwork_show and send it back with patchwork_replace. Makes a new version; patchwork_undo reverses it.
Inputs: name (required), values (required), dry_run, message.
patchwork_append_stepsAdd steps at the end of a scriptA
Add steps at the end of an existing script and keep the steps it has. Use it instead of patchwork_set_steps when no existing step changes. The whole script is re-read, and the version is dropped with an error if a step came back different. To create the script, use patchwork_add_script. Makes a new version; patchwork_undo reverses it.
Inputs: steps (required), script (required), dry_run, message.
patchwork_deleteDelete an object from the working copyADestructive
Delete a script, layout, value list, custom function or field. Refused, with the list of what references it, when other objects reference it: show that list to the user, and only then retry with force=true. With force the references are left pointing at nothing and the result lists them for review. Makes a new version; patchwork_undo reverses it.
Inputs: kind (required), name (required), force, dry_run, +1 more.
patchwork_listList the objects of the file by kindARead-onlyIdempotent
List the names of the objects of one kind, one per line. Without kind, returns a count per kind instead. kind=fields needs table and returns each field as name, tab, type, with (calc) for a calculation. Use it to get exact names before patchwork_show, patchwork_uses or any edit.
Inputs: kind, table.
patchwork_logShow the version history of the working copyARead-onlyIdempotent
List every version of the working copy, oldest first, with its time, its message and up to 10 of its changes. Use it to review what was done, or to count how many patchwork_undo calls lead back to a version. For the current version only, use patchwork_status.
Inputs: no named parameters.
patchwork_openOpen a FileMaker file as a working copyADestructive
Open a closed .fmp12 file as a new versioned working copy (v000) and return its summary: version, account and object counts. Call it first: every other tool works on this working copy. The source file is never modified, but it must be closed in FileMaker. Refused when a workspace already exists in the project folder, unless force=true, which deletes that workspace and all its versions. The password is read from the PATCHWORK_PASSWORD environment variable, never from an argument.
Inputs: source (required), account (required), force, project, +1 more.
patchwork_paletteList the colors a theme usesARead-onlyIdempotent
List the colors a theme uses, as the theme name then one line per 6-digit hex color with its count, most frequent first. Use it to choose the keys of the colors map of patchwork_retheme or patchwork_recolor_layouts.
Inputs: theme.
patchwork_place_fieldPut an existing field on a layoutA
Put a field on a layout. Copies the look and label of near, a field already on the layout, and inserts a row below it: objects underneath move down and the part grows. Refused when the field is already on the layout, or when side=right has no room. The version is dropped with an error if the field is not on the layout in the result. To create the field first, use patchwork_add_field. Makes a new version; patchwork_undo reverses it.
Inputs: near (required), field (required), layout (required), side, +3 more.
patchwork_pushApply a hand-written FMUpgradeTool patchADestructive
Apply a hand-written FMUpgradeToolPatch. A last resort for changes no other tool covers: prefer the specific tools, which check their result object by object. Here only a patch that FMUpgradeTool skipped entirely is detected and refused. Makes a new version; patchwork_undo reverses it.
Inputs: patch_xml (required), dry_run, message.
patchwork_recolor_layoutsRestyle layouts or swap a field on themA
Rewrite, in one version, every layout that would change: colors and fonts set on layout objects, or one field swapped for another everywhere it appears. Use it for local styling that patchwork_retheme does not reach. Fails with 'No layout would change.' when nothing matches. Makes a new version; patchwork_undo reverses it.
Inputs: only, fonts, colors, dry_run, +2 more.
patchwork_replaceReplace a whole object with edited XMLADestructive
Replace a whole layout, theme, value list or custom function with edited XML. Get the XML from patchwork_show, edit it, and send all of it back: anything you leave out is lost. Use it when no specific tool fits; prefer patchwork_place_field, patchwork_retheme and patchwork_recolor_layouts for what they cover. Scripts go through patchwork_set_steps. Makes a new version; patchwork_undo reverses it.
Inputs: xml (required), kind (required), name (required), dry_run, +1 more.
patchwork_rethemeChange the colors, fonts or name of a themeA
Rewrite one theme: replace colors, replace fonts, or change its display name. Read the current colors with patchwork_palette first. For colors and fonts set on layout objects rather than in the theme, use patchwork_recolor_layouts. Makes a new version; patchwork_undo reverses it.
Inputs: fonts, theme, colors, rename, +2 more.
patchwork_saveWrite the current version to a new .fmp12 fileADestructive
Write the current version to a new .fmp12 file that FileMaker can open. The working copy and its versions stay as they are, so you can go on editing and save again. Refused when the destination is the source file, or when it exists and force is not true.
Inputs: dest (required), force.
patchwork_set_stepsReplace all the steps of a scriptA
Replace all the steps of an existing script. Read the script with patchwork_show, edit the text, and send the whole text back: steps you leave out are removed. Lines left as they were keep their step exactly, whatever the step. Each step is re-read, and the version is dropped with an error if one came back different. To only add steps at the end, use patchwork_append_steps. Makes a new version; patchwork_undo reverses it.
Inputs: steps (required), script (required), dry_run, message.
patchwork_showShow the definition of one objectARead-onlyIdempotent
Return the definition of one object, to read it or to edit it and send it back. A script comes as FileMaker text, one step per line, ready for patchwork_set_steps. Any other kind comes as its Save-as-XML block, ready for patchwork_replace. kind=step returns the XML of a real step of that name found in the file, as a model for steps the text form cannot write. Fails with 'not found' on an unknown name: get exact names from patchwork_list.
Inputs: kind (required), name (required), xml.
patchwork_statusShow the state of the working copyARead-onlyIdempotent
Summary of the working copy: source file, current version with its message and time, account, and counts of tables, layouts, scripts, value lists and custom functions. Use it to check that a file is open and which version you are on. For every version use patchwork_log; for object names use patchwork_list.
Inputs: no named parameters.
patchwork_undoDrop the last version of the working copyADestructive
Drop the last version of the working copy and go back to the one before. Its files are deleted: there is no redo. One call drops one version; call it again to go further back. Fails on v000, the opened file. The source file and the files written by patchwork_save are not touched.
Inputs: no named parameters.
patchwork_usesFind what uses an object of the fileARead-onlyIdempotent
Report what uses an object, without changing anything: references (certain) and mentions of its name in calculations (possible). Call it before patchwork_delete or before renaming, to see what would break. Answers 'Nothing in the file uses ...' when nothing does.
Inputs: kind (required), name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target a distinct resource+action, and the descriptions actively disambiguate the tricky pairs (add_script vs set_steps vs append_steps, retheme vs recolor_layouts, replace vs push). The main residual overlap is patchwork_replace, which can touch layouts, themes, value lists and custom functions and thus shadows the specialised tools, though the descriptions explicitly steer callers elsewhere first.
All 21 tools share the patchwork_ prefix and snake_case, with verb_noun forms (add_field, place_field, set_steps, recolor_layouts) dominating. A handful of read-only tools use bare nouns (status, log, palette, uses), which is a minor but readable deviation.
21 tools sits at the heavy end of the scale, but the domain genuinely spans file lifecycle, object CRUD across five object kinds, script step editing, styling, versioning and export, so most tools earn their place. The surface could be tightened (replace and push are catch-alls) but nothing is obviously redundant.
The lifecycle is well covered: open, inspect, add/edit/delete objects, version with undo and log, and save out to a new .fmp12. Gaps remain for creating tables or layouts from scratch and for renaming objects (the uses tool hints at renaming but no rename tool exists), forcing callers into raw XML via replace or push.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
FixMyPrompt is a remote MCP server for coding agents. It saves the steps your agent worked out as project memories and fetches them in later sessions, scores and rewrites prompts, and checks CLAUDE.md and AGENTS.md files. Works with Claude Code, Codex and Cursor. Free plan available.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server that gives Claude Desktop and other desktop MCP clients filesystem powers—read, write, edit, and manage files like AI coding assistants.1777 npm9MIT
- AlicenseAqualityDmaintenanceMCP server that combines Read+Edit file operations into single tool calls. 80-95% fewer tool calls formulti-file refactoring across Claude, Cursor, Windsurf, and more.330 npm3MIT
- AlicenseAqualityCmaintenanceAn MCP server that provides AI assistants with direct access to FileMaker databases via OData v4 API, enabling CRUD operations, script execution, and schema introspection.196MIT
- AlicenseBqualityDmaintenanceAn MCP server that connects Claude to FileMaker databases via the Data API, enabling natural language queries, record management, layout exploration, and script execution.11MIT