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?"
• "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_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 | | get_test_result | Full record + every measurement value | | 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 | | 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). |

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

1. Open FormLab
2. Sidebar → ⇅ Import / Export
3. Click Export — saves formlab-export-YYYY-MM-DD.json to your downloads folder
4. 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.

1. In FormLab (Pro): Settings → Account → AI tools (MCP) → Connect…
2. Copy the generated config and paste it into Claude Desktop (it merges with the file-mode example below).

The config sets these env vars (which switch the server into cloud mode):

| Env var | Value | |---|---| | FORMLAB_SUPABASE_URL | your Supabase project URL (public) | | FORMLAB_SUPABASE_ANON_KEY | publishable/anon key (public) | | FORMLAB_REFRESH_TOKEN | your session refresh token — a credential | | FORMLAB_WORKSPACE_ID | (optional) workspace to read; defaults to your own | | FORMLAB_REFRESH_SECONDS | (optional) poll interval, default 60 |

When FORMLAB_REFRESH_TOKEN + URL + key are present, the server reads the workspace directly (RLS-scoped to you), re-fetching every FORMLAB_REFRESH_SECONDS. It's read-only.

⚠ Security. The refresh token grants read access to your account — treat the config like a password (don't share or commit it). To revoke: FormLab → Account → Sign out of all devices. A dedicated, revocable, read-only MCP token is the planned hardening (needs a small backend: a tokens table + an Edge Function to mint/validate).

Cloud mode needs @supabase/supabase-js (a normal dependency) — npm install in this folder, or npx -y formlab-mcp pulls it automatically.

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