Filemaker Mcp Server

FileMaker MCP Server

An MCP (Model Context Protocol) server that connects Claude to FileMaker databases. Once installed, Claude can read, write, and query your FileMaker data using natural language — through Cowork, Claude Desktop, or the Claude API.

Claude ↔ MCP ↔ this server ↔ FileMaker OData / Data API

Features

• OAuth 2.0 — Cowork opens the FileMaker login page automatically; no manual token handling
• Multi-tenant — one running instance serves multiple FileMaker hosts and databases
• Both transports — Streamable HTTP (modern) and SSE (legacy) for maximum client compatibility
• Direct SQL — aggregate queries via MCP.ExecuteSQL (GROUP BY, JOIN, SUM, etc.)
• Signed tokens — HMAC-SHA256 tokens with configurable expiration (optional)
• Prometheus metrics — per-tenant latency, session counts, and error counters
• Hot-reloadable descriptions — update tool descriptions at runtime via a single API call
• Production-ready — rate limiting, request logging, Cloudflare Tunnel compatible

Requirements

| Requirement | Minimum version | |---|---| | FileMaker Server | 19.x or later | | Node.js | 18.0.0 or later | | OData API | Enabled in FileMaker Server Admin Console |

Quick install

curl -fsSL https://raw.githubusercontent.com/ibrahim-bittar/filemaker-mcp-server/main/install.sh | bash

The installer handles Node.js, pm2, dependencies, .env generation, and service startup.

Manual install

git clone https://github.com/ibrahim-bittar/filemaker-mcp-server.git
cd filemaker-mcp-server
npm install
cp .env.example .env
# Edit .env with your settings
node server.js

Configuration

Edit .env (created automatically by the installer):

| Variable | Description | Required | |---|---|---| | PORT | Port the server listens on | No (default: 3100) | | MCP_PUBLIC_URL | Externally reachable URL (e.g. https://mcp.yourdomain.com) | When behind a proxy/tunnel | | TOKEN_SECRET | Secret for HMAC-SHA256 token signing | No (falls back to plain base64) | | ADMIN_SECRET | Secret for admin endpoints | No (disables admin if empty) | | CERT_PATH | Path to TLS certificate (PEM) | For HTTPS mode | | KEY_PATH | Path to TLS private key (PEM) | For HTTPS mode | | NODE_TLS_REJECT_UNAUTHORIZED | Set to 0 for self-signed FM certificates | No |

> FileMaker host and database are NOT in .env. They go in the connector URL as ?host= and ?db= query parameters, which enables multi-tenant support from a single server.

Connector URL format

https://mcp.yourdomain.com/mcp?host=&db=

| Parameter | Example | Description | |---|---|---| | host | fm.yourdomain.com | FileMaker Server hostname or IP | | db | MyDatabase | FileMaker database name (OData-exposed) |

Connecting in Cowork

1. Open Settings → Connectors → Add custom connector
2. Name: FileMaker MCP (or anything you like)
3. URL: https://mcp.yourdomain.com/mcp?host=fm.yourdomain.com&db=MyDatabase
4. Click Connect — Cowork opens the FileMaker login page automatically

Built-in tools

The server ships with six tools that cover all three FileMaker API patterns:

| Tool | Pattern | Description | |---|---|---| | fm_query | OData GET | Read records from any table with filters, sorting, and pagination | | fm_run_script | Script call | Execute any FileMaker script by name | | fm_patch_record | OData PATCH | Update specific fields on an existing record | | fm_sql | SQL via script | Run aggregate SQL queries (GROUP BY, JOIN, SUM) | | fm_get_schema | OData metadata | List all tables and their field names and types | | fm_get_current_user | Script call | Get the authenticated user's profile and permissions |

Example: read records

Claude: Show me all customers from California with a balance over $10,000

Claude calls fm_query with table: "Customers", filter: "State eq 'CA' and Balance gt 10000".

Example: run a script

Claude: Create a new invoice for customer 4821, project "Website Redesign", $5,500 USD

Claude calls fm_run_script with script: "API_CreateInvoice" and the appropriate parameters.

Example: aggregate report

Claude: What were the top 5 products by revenue last quarter?

Claude calls fm_sql with a GROUP BY query joining your Products and Orders tables.

Adding custom tools

To expose your own FileMaker scripts or OData tables as dedicated tools:

1. Add a tool definition in server.js (in the TOOLS array):

{
  name: 'my_create_order',
  description: 'Creates a new sales order for a customer.',
  inputSchema: {
    type: 'object',
    properties: {
      customer_id: { type: 'number', description: 'Customer ID' },
      product:     { type: 'string', description: 'Product name' },
      quantity:    { type: 'number', description: 'Number of units' },
    },
    required: ['customer_id', 'product', 'quantity'],
  },
},

2. Add a handler in handleTool() (in the switch statement):

case 'my_create_order': {
  return await runScript('API_Orders_Create', {
    CustomerID: args.customer_id,
    Product:    args.product,
    Quantity:   args.quantity,
  }, authHeader, odataBase, db);
}

That's it. The tool is immediately available to Claude.

The MCP.ExecuteSQL script (required for fm_sql)

fm_sql delegates to a FileMaker script named MCP.ExecuteSQL. Create it in FileMaker:

Script: MCP.ExecuteSQL
Parameter: JSON object with a "sql" key

Steps:
  Set Variable [$sql; Value: JSONGetElement(Get(ScriptParameter); "sql")]
  Set Variable [$result; Value: ExecuteSQL($sql; Char(9); Char(10))]
  Exit Script [Result: JSONSetElement("{}"; "rows"; $result; JSONString)]

> Tip: Add error handling with Get(LastError) and return { "error": "..." } for debugging.

Generating tokens manually

If you need to generate a signed token without going through OAuth (e.g. for testing or for clients that don't support OAuth):

node generate-token.js   [days]
# Example: node generate-token.js admin MyPass 90

Or use the HTTP endpoint (useful for FileMaker Insert From URL scripts):

POST https://mcp.yourdomain.com/auth/token?host=fm.yourdomain.com&db=MyDatabase
Content-Type: application/json

{ "username": "admin", "password": "MyPass", "days": 365 }

Returns:

{
  "ok": true,
  "username": "admin",
  "token": "...",
  "url": "https://mcp.yourdomain.com/mcp?host=fm.yourdomain.com&db=MyDatabase&token=...",
  "expires": "2027-06-03",
  "days": 365,
  "mode": "HMAC-SHA256"
}

Admin API

All admin endpoints require the X-Admin-Secret header matching ADMIN_SECRET in .env.

Update tool descriptions at runtime

curl -X POST https://mcp.yourdomain.com/admin/sync-dictionary \
  -H "X-Admin-Secret: your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{ "descriptions": { "fm_query": "Your custom description for fm_query..." } }'

Descriptions are merged (not replaced) with the existing file and hot-reloaded immediately — no server restart needed.

View current descriptions

curl https://mcp.yourdomain.com/admin/get-descriptions \
  -H "X-Admin-Secret: your-admin-secret"

Endpoints reference

| Method | Path | Description | |---|---|---| | GET | /health | Server status (no auth required) | | POST | /mcp | Initialize or continue an MCP session (Streamable HTTP) | | GET | /mcp | SSE notifications for an existing MCP session | | DELETE | /mcp | Close an MCP session | | GET | /sse | Legacy SSE transport | | POST | /messages | Messages for legacy SSE sessions | | GET | /metrics | Prometheus metrics (requires ADMIN_SECRET) | | POST | /auth/token | Generate a signed connector token | | POST | /admin/sync-dictionary | Update tool descriptions at runtime | | GET | /admin/get-descriptions | View current tool descriptions | | GET | /.well-known/oauth-protected-resource | OAuth resource metadata (RFC 9728) | | GET | /.well-known/oauth-authorization-server | OAuth server metadata (RFC 8414) | | POST | /register | Dynamic client registration (RFC 7591) | | GET | /oauth/authorize | FileMaker login page | | POST | /oauth/authorize | Process login and issue auth code | | POST | /oauth/token | Exchange auth code for access token |

Deploying with Cloudflare Tunnel

Cloudflare Tunnel is the easiest way to expose the server to the internet without opening firewall ports:

# Install cloudflared and authenticate
brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel login

# Create a named tunnel
cloudflared tunnel create filemaker-mcp

# Route your domain to the tunnel
cloudflared tunnel route dns filemaker-mcp mcp.yourdomain.com

# Run the tunnel (HTTP → Cloudflare handles TLS)
cloudflared tunnel run --url http://localhost:3100 filemaker-mcp

Set MCP_PUBLIC_URL=https://mcp.yourdomain.com in .env. The server runs in HTTP mode locally; Cloudflare terminates TLS externally.

pm2 commands

# View logs
pm2 logs filemaker-mcp-server

# Restart
pm2 restart filemaker-mcp-server

# Stop
pm2 stop filemaker-mcp-server

# Start (after manual stop)
pm2 start filemaker-mcp-server

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ibrahim-bittar
• Source: ibrahim-bittar/filemaker-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.