Skip to main content
Glama

CI Stars License: MIT Python 3.10+ FileMaker 2026 MCP server Zero dependencies PRs welcome M8ven Score M8ven Score Patchwork MCP server – quality and maintenance score on Glama

Patchwork MCP server – quality and maintenance score on Glama

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 .fmp12 file. 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 .fmp12 and 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 Antigravity

No 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? undo always works

🔒 Protects the original

Everything happens on a working copy. save writes a new file and never overwrites yours

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 init

Then

Claude Code

.mcp.json · CLAUDE.md · .claude/skills/

Run claude in the folder and approve patchwork

Cursor

.cursor/mcp.json · .cursor/skills/

Enable patchwork in Settings › MCP

⌨️ Codex

.codex/config.toml · AGENTS.md · .agents/skills/

Trust the project when Codex asks

Antigravity

.agents/mcp_config.json · AGENTS.md · .agents/skills/

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

TIP

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

open SRC --account NAME

Starts a working copy in .patchwork/ (version v000). The source is never modified

status, log

Current version, and every version with what changed

ls [KIND] [TABLE]

Lists layouts, scripts, value lists, custom functions, themes, tables, fields

show KIND NAME

Prints a script as FileMaker text (--xml for XML), anything else as XML. show step NAME prints a real example of a step

palette [--theme NAME]

Colors a theme uses, most frequent first

add-field TABLE NAME

Adds a field: --type, --calc, --global, --image logo.png

add-value-list NAME VALUES...

Adds a custom value list

add-custom-function NAME --calc

Adds a custom function, with --param

add-script NAME STEPS.txt

Creates a script from FileMaker script text (or <Step> XML)

set-steps, append-steps

Rewrites a script with edited text from show, or adds steps at the end

place-field LAYOUT TO::FIELD --near FIELD

Puts a field on a layout below another one, with a copy of its look and label. --side right, --label

add KIND FILE.xml

Adds a value list or a custom function from XML

replace KIND NAME FILE.xml

Replaces an object with your edited version of show

uses KIND NAME

Lists what references an object, and where its name appears in calculations

delete KIND NAME

Deletes a script, layout, value list, custom function or field. Refused while other objects reference it, unless --force

retheme, recolor-layouts

Rewrites colors and fonts of a theme, or of the layouts' local styles

push PATCH.xml

Applies a hand-written FMUpgradeTool patch, with the same checks

undo

Drops the last version

save DEST

Writes the current version to a new .fmp12

rebrand SRC DEST --brand brand.json

One shot: colors, fonts, logo and theme name on a whole solution

mcp

The MCP server for agents

init DIR

Wires a folder for Claude Code, Cursor, Codex and Antigravity

doctor

Shows which Claris tools Patchwork found. Exit code 2 if one is missing

tool guids|export|validate|apply|new-file

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

PATCHWORK_PASSWORD

Password of the account given to open. Required unless --no-password. Never printed

PATCHWORK_KEY

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

PATCHWORK_PROJECT

Project folder holding .patchwork/, when -C is not given. Not used by open

FM_UPGRADE_TOOL, FM_DEVELOPER_TOOL

Paths of the Claris tools, when doctor does not find them

PATCHWORK_ALLOW_OUTSIDE

1 lets MCP tools use force outside the project folder. Not in release 0.1.0

PATCHWORK_TOOL_TIMEOUT

Seconds before a Claris tool that does not answer is stopped. Default 1800. Not in release 0.1.0

PATCHWORK_SAMPLE

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 tests

The 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 registry

How 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 ScriptReference inside each ScriptStepReference.

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 tools
patchwork_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 copyA
Destructive

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 kindA
Read-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 copyA
Read-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 copyA
Destructive

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 usesA
Read-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 patchA
Destructive

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 XMLA
Destructive

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 fileA
Destructive

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 objectA
Read-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 copyA
Read-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 copyA
Destructive

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 fileA
Read-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

    A4.2/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      3
      30 npm
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that provides AI assistants with direct access to FileMaker databases via OData v4 API, enabling CRUD operations, script execution, and schema introspection.
      19
      6
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that connects Claude to FileMaker databases via the Data API, enabling natural language queries, record management, layout exploration, and script execution.
      11
      MIT