formlab-mcp

formlab-mcp

A read-only Model Context Protocol server for FormLab. Lets Claude (or any MCP-compatible AI assistant) read and analyze your local FormLab database — your formulations, ingredients, batches, samples and test reports — without your data ever leaving your machine.

Local-first + AI-native. Your proprietary recipes stay on your laptop; only the LLM's answer to your question travels.

Listed in the official MCP Registry as io.github.juliu1980/formlab-mcp.

What it does

Ask Claude (or another MCP client) things like:

• "Which of my formulations use silicone fluid at 5% or more?"
• "Compare the composition of Formula FORM-001 and FORM-004 side by side."
• "What parameters fail most often in Q2 testing?"
• "Show me the DOE matrix at sample grain for all 'Anti-aging serum' family formulas."
• "What's untested? Which of my approved formulas have no measurements yet?"
• "Map the design space of my WallPaint project — which ingredients vary, and what combination haven't I tried yet?"
• "List all peptide ingredients with purity above 95%."
• "Which botanicals do I source from Madagascar?"
• "Find ingredients where the sequence contains KTTKS."

Tools exposed

Tool	Purpose
list_formulations	Filtered list of recipes
get_formulation	Full record + flattened wt-% composition (sub-formulas expanded)
find_similar_formulations	Find formulas using a given ingredient ≥ threshold %
compare_formulations	Pairwise side-by-side composition diff
list_ingredients	Filtered list of raw materials. Filters: family, supplier, name_contains, in_stock_only, ingredient_class (small-molecule / surfactant / polymer / extract / fragrance / pigment / sequence / mixture), sequence_contains (e.g. KTTKS → Matrixyl), taxon_contains (e.g. Centella)
get_ingredient	Full record + supplier / cost ($/kg) / stock / formulations using it, plus GHS safety (pictograms, H/P codes, signal word), per-jurisdiction regulatory status, and inventory lots (balances + expiry). Returns every class-specific sub-object when present: sequence (peptide / oligo), taxon (NCBI ID + scientific name), ingredientClass, extractDetails, sequenceDetails, polymerDetails, surfactantDetails, pigmentDetails, fragranceDetails
list_lots	Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry). Filters: ingredient_id, expiring_within_days, status
list_inventory	Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ reorderThreshold, or zero). Filters: low_stock_only, expiring_within_days, family
list_batches	Filtered list of production / lab-prep events
get_batch	Full record + actual composition + samples + blend lineage
list_samples	Filtered list of physical specimens
get_sample	Full record + canonical variant + test reports + blend lineage
list_test_results	Filtered list of test reports (by sample, parameter, measured-value range (value_min/value_max), date, or lab)
get_test_result	Full report: every measurement's value, spec, and the resolved instrument (instrumentSource: row / method / run)
get_doe_matrix	Pivot matrix (CSV by default) — rows × ingredients × parameters
find_failures	Pareto-style: parameters that fail acceptance most often
get_coverage_matrix	Which formulations × parameters have been measured (TEST coverage)
get_design_space	COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested interior gap as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised 2-component PCA of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers "where haven't I explored?" / "what should I formulate next?"
list_doe_designs	Saved DOE designs — the recipe behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: project, design_type, constrained_only, name_contains
get_doe_design	One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became
find_by_smarts	SMARTS-pattern substructure search across every ingredient with a SMILES. Requires @rdkit/rdkit (optional dependency — install with npm install @rdkit/rdkit in mcp/ if you get a "not installed" error). Examples: c1ccccc1 (any aromatic 6-ring), [OX2H1] (any hydroxyl), C(=O)O (carboxylic acid), [F,Cl,Br,I] (any halogen).
list_equipment	Filtered list of the Equipment registry (mixers, ovens, viscometers, balances…). Filters: category, status, manufacturer, name_contains
get_equipment	Full equipment record + a summary of where it's used (panels, step presets, test methods, formulas, batches)
list_test_methods	Filtered list of Test Methods (the parameter library). Filter by analyte (the property measured, e.g. Viscosity — finds every method for it), category, name_contains, include_retired
get_test_method	Full method definition (SOP / sample prep / equipment / calculation / acceptance spec) + sibling methods sharing its analyte
list_step_presets	Filtered list of Step Presets (reusable procedure steps: duration / temp / RPM / equipment). Filters: industry, name_contains
get_step_preset	Full step-preset record incl. the multi-value equipment list ({name, equipmentId})
list_test_panels	Filtered list of Test Panels (reusable column-sets — the parameters measured together on a sample). Filters: industry, name_contains
get_test_panel	Full panel record — ordered parameter list (each with resolved Test Method UID, unit, spec) + instruments
list_projects	Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: status, name_contains
get_project	Full project record + the formulations filed under it
list_notebook_entries	ELN feed — dated authored notes attached to records. Filters: entity_type, entity_id, author, text_contains, since, until
get_notebook_entry	One notebook entry — full body, author, attachment metadata, resolved linked record

Install

# Run directly without installing — recommended:
npx formlab-mcp /path/to/formlab-export.json

# Or install globally for repeated use:
npm install -g formlab-mcp
formlab-mcp /path/to/formlab-export.json

For local development from this repo:

cd mcp
npm install
node index.js /path/to/formlab-export.json

Requires Node 18+.

Get your FormLab export

• Open FormLab
• Sidebar → ⇅ Import / Export
• Click Export — saves formlab-export-YYYY-MM-DD.json to your downloads folder
• Point this MCP at the downloaded file

The MCP server watches the file — re-export from FormLab and the next tool call sees the fresh data without restarting the server.

Or: LIVE cloud mode (no export needed)

Instead of an export file, point the server at your live cloud workspace so it's always current.

• In FormLab (Pro): Settings → Account → AI tools (MCP) → Connect…
• Click Create token, copy the generated config, and paste it into Claude Desktop.

The config sets a single env var, which switches the server into cloud mode:

Env var	Value
FORMLAB_MCP_TOKEN	a dedicated, read-only, revocable token (flmcp_…)
FORMLAB_SUPABASE_URL	(optional) override the backend URL — defaults to production
FORMLAB_SUPABASE_ANON_KEY	(optional) override the publishable key — defaults to production
FORMLAB_REFRESH_SECONDS	(optional) poll interval, default 60

When FORMLAB_MCP_TOKEN is present, the server POSTs it to FormLab's mcp-data Edge Function, which returns your workspace scoped to you by row-level security and re-fetches every FORMLAB_REFRESH_SECONDS. It's read-only — enforced at the database (a dedicated mcp_readonly Postgres role with SELECT-only grants), not by trust.

Security. The token grants read-only access to one workspace and holds no account session — only a SHA-256 hash is stored server-side, and it never rotates. Treat the config like a password (don't share or commit it). Revoke or re-mint any time from Settings → Account → AI tools (MCP) → Connect.

Cloud mode has no extra dependency — it's a plain fetch.

Wire it up to Claude Desktop

Add this to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "formlab": {
      "command": "npx",
      "args": ["formlab-mcp", "/Users/you/Downloads/formlab-export-2026-05-30.json"]
    }
  }
}

Or for local-dev (from the repo):

{
  "mcpServers": {
    "formlab": {
      "command": "node",
      "args": [
        "/Users/you/Documents/GitHub/formlab/mcp/index.js",
        "/Users/you/Downloads/formlab-export-2026-05-30.json"
      ]
    }
  }
}

Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 33 tools become callable in any conversation.

Wire it up to Claude Code

claude mcp add formlab npx formlab-mcp /Users/you/Downloads/formlab-export.json

Or with a stored env var:

export FORMLAB_EXPORT=/Users/you/Downloads/formlab-export-2026-05-30.json
claude mcp add formlab npx formlab-mcp

Privacy and architecture

• No network calls. The server runs on stdio between Claude and your local Node process. Your data file never leaves your disk.
• No FormLab cloud. FormLab itself is a local-first app; the MCP follows the same model.
• Hot-reload on file change. Re-export from FormLab while the server is running — the next tool call picks up fresh data.
• Read-only. Tier 1 cannot mutate your FormLab data. (Write tools are planned for a future paid "Pro" tier — register / batch / log-test mutations with cascade-safe confirmation.)

Data shape

The server accepts both FormLab export shapes:

• Wrapped FAIR export: { "fair": {...metadata...}, "data": {...db...} }
• Legacy bare-db JSON: {...db...} directly

The wrapped form is the default since 2026; the legacy form is supported for older exports.

Tier 2 (planned, paid)

Live file-sync with write tools: create_formulation, update_formulation, log_test_result, create_batch, etc. Mutations from Claude write back to the same JSON FormLab reads. Conflict detection, cascade-safe deletes, schema versioning.

Not yet shipped — see the FormLab roadmap.

License

MIT