filemaker-odata-mcp

FileMaker Server OData MCP

Model Context Protocol (MCP) server providing FileMaker Server OData 4.01 API integration for AI assistants like Claude Desktop, Windsurf, Cursor, and Cline.

Features

• 35 MCP Tools for FileMaker database operations (29 standard + 6 optional schema editing)
• Multi-File Support - Connect to multiple databases simultaneously (fm_odata_connect_multi)
• Session Management - List and target active sessions per call (fm_odata_list_active_sessions, per-call connection param)
• Schema Discovery - Merged schema across all active sessions (fm_odata_describe_sessions)
• Database Discovery - Explore tables, fields, and metadata
• CRUD Operations - Create, read, update, and delete records
• Secure Connections - SSL support for self-signed certificates
• Connection Management - Save and reuse database connections
• OData 4.01 Standard - Full query capabilities ($filter, $select, $orderby, $apply, etc.)
• Password Redaction - Credentials are scrubbed from debug logs
• FileMaker 2025 Aggregation - Server-side $apply via fm_odata_aggregate (v22.0.1+)
• Type Casting & Parameterized Filters - fm_odata_cast and fm_odata_build_filter (v21.1+)
• Server Version Detection - fm_odata_get_server_version reports the FM Server version and a feature-compatibility map; version-gated tools fall back gracefully on older servers
• FileMaker 2026 Metadata Comments - Table/field comments and AI annotations extracted from $metadata on v26+ servers (fm_odata_list_tables with includeDetails, enriched fm_odata_describe_sessions output)
• Automatic FMFID Resolution (v26+) - Non-ASCII field names are automatically resolved to stable internal FMFID IDs in $filter expressions, eliminating double-quote escaping and preventing breakage on field renames. Falls back to auto-quoting on older servers.
• Script Execution by FMSID (v26+) - Run FileMaker scripts by stable internal FMSID instead of script name, preventing integration breakage when scripts are renamed. fm_odata_list_scripts exposes IDs so agents can prefer ID-based calls.
• Schema Editing (DDL) - Create/alter/delete tables, fields, and indexes via FileMaker's OData schema endpoints (opt-in with FM_ALLOW_SCHEMA_EDITS=true)

Quick Start

Installation

# Via NPM (recommended)
npm install -g filemaker-odata-mcp

# Or local development
git clone https://github.com/fsans/FMS-ODATA-MCP.git
cd FMS-ODATA-MCP
npm install
npm run build

Deployment Modes

1. MCP Server Mode (Default)

For use with AI assistants that support MCP (Claude Desktop, Windsurf, Cursor, Cline).

Setup for Claude Desktop

1. Locate your Claude config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server:

{
  "mcpServers": {
    "filemaker-odata": {
      "command": "npx",
      "args": ["-y", "filemaker-odata-mcp"],
      "env": {
        "FM_SERVER": "https://your-filemaker-server.com",
        "FM_DATABASE": "YourDatabase",
        "FM_USER": "your-username",
        "FM_PASSWORD": "your-password",
        "FM_VERIFY_SSL": "true",
        "FM_ALLOW_SCHEMA_EDITS": "false"
      }
    }
  }
}

Schema editing is disabled by default. The 6 schema (DDL) tools (fm_odata_create_table, fm_odata_add_fields, fm_odata_delete_table, fm_odata_delete_field, fm_odata_create_index, fm_odata_delete_index) are not registered unless FM_ALLOW_SCHEMA_EDITS is set to "true". When "false" (default), these tools are completely absent from the tool list and cannot be called. Set to "true" only if your FileMaker account has full-access (schema modification) privileges.

1. For self-signed SSL certificates, set FM_VERIFY_SSL to "false"

2. Restart Claude Desktop

Setup for Windsurf/Cursor

The server will be automatically detected when installed globally. For local development, add to your MCP config.

2. Standalone HTTP Server Mode

Run as a standalone HTTP server accessible from any application:

# Set environment variables for HTTP mode
export MCP_TRANSPORT=http
export MCP_PORT=3333
export MCP_HOST=0.0.0.0  # Listen on all interfaces

# Run the server
filemaker-odata-mcp

The server will start on http://localhost:3333 with the following endpoints:

• MCP endpoint: http://localhost:3333/mcp (POST requests with JSON-RPC 2.0)
• Health check: http://localhost:3333/health
• Server info: http://localhost:3333/mcp (GET request)

Example HTTP Client Request

curl -X POST http://localhost:3333/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

HTTPS Mode

export MCP_TRANSPORT=https
export MCP_PORT=3443
export MCP_CERT_PATH=/path/to/cert.pem
export MCP_KEY_PATH=/path/to/key.pem

Integration Examples

Python Example:

import requests

# List available tools
response = requests.post("http://localhost:3333/mcp", json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
})
tools = response.json()

# Query records
response = requests.post("http://localhost:3333/mcp", json={
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "fm_odata_query_records",
        "arguments": {
            "table": "Contacts",
            "filter": "City eq 'New York'"
        }
    }
})

JavaScript Example:

// Connect to FileMaker
const response = await fetch('http://localhost:3333/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'tools/call',
        params: {
            name: 'fm_odata_connect',
            arguments: {
                server: 'https://your-server.com/fmi/odata/v4',
                database: 'Contacts',
                user: 'admin',
                password: 'secret',
                verifySsl: false
            }
        }
    })
});

3. Docker Deployment

Option A: Using start.sh (Recommended)

The included start.sh script handles building, credential injection from .env, and container lifecycle:

git clone https://github.com/fsans/FMS-ODATA-MCP.git
cd FMS-ODATA-MCP
cp .env.example .env
# Edit .env with your FileMaker credentials and set MCP_TRANSPORT=http, MCP_HOST=0.0.0.0
./start.sh

The script will build TypeScript, build the Docker image, remove any existing container, and start a fresh one. Logs are tailed automatically.

Option B: Using Docker Run

# Clone and build
git clone https://github.com/fsans/FMS-ODATA-MCP.git
cd FMS-ODATA-MCP
npm run build
docker build -t filemaker-odata-mcp:latest .

# Run the container
docker run -d \
  --name filemaker-odata-mcp \
  -p 3333:3333 \
  -e FM_SERVER=https://your-filemaker-server.com \
  -e FM_DATABASE=YourDatabase \
  -e FM_USER=your-username \
  -e FM_PASSWORD=your-password \
  -e FM_VERIFY_SSL=false \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -v ~/.fms-odata-mcp:/home/mcp/.fms-odata-mcp \
  filemaker-odata-mcp:latest

Important: Set MCP_HOST=0.0.0.0 when running in a container. Using localhost binds only to the container's loopback interface and makes the port unreachable from outside.

Option C: Using Docker Compose

1. Clone and build:

git clone https://github.com/fsans/FMS-ODATA-MCP.git
cd FMS-ODATA-MCP
npm run build

1. Configure environment:

cp docker-compose.yml my-docker-compose.yml
# Edit my-docker-compose.yml with your FileMaker credentials

1. Start the server:

docker-compose -f my-docker-compose.yml up -d

Option D: Docker Compose with HTTPS

# Start with Nginx reverse proxy for HTTPS
docker-compose -f docker-compose.yml --profile https up -d

Place your SSL certificates in the ./ssl directory:

• ssl/cert.pem - SSL certificate
• ssl/key.pem - SSL private key

Docker Features

• Health checks - Automatic monitoring of server status
• Persistent connections - Mount volume to save connection configurations
• Non-root user - Security best practices
• Alpine Linux - Small image size (~50MB)
• Signal handling - Graceful shutdown with dumb-init

Accessing the Server

Once running, access the server at:

• HTTP: http://localhost:3333
• HTTPS (with Nginx): https://localhost

Check the health endpoint:

curl http://localhost:3333/health

4. Dify Integration

To use this server as an MCP tool in Dify:

1. Start the server in HTTP mode (see Docker Deployment above)
2. In Dify, add a new MCP tool with:
   • Transport: streamable_http
   • URL: http://host.docker.internal:3333/mcp (if Dify runs in Docker on the same host)
3. No authentication headers are required

Note: If Dify returns a 403 error, check your SSRF proxy configuration. Dify uses a Squid proxy to prevent SSRF attacks — port 3333 must be added to the Safe_ports ACL in squid.conf.

First Steps

Once connected, try these prompts in Claude:

What tables are in my FileMaker database?

Show me the first 5 records from the Contacts table

Find all contacts where LastName equals "Smith"

Create a new contact with name "John Doe" and email "john@example.com"

Documentation

• Quick Reference - One-page setup guide
• Prompt Examples - Complete prompt reference
• Claude Desktop Setup - Detailed configuration
• Docker Deployment - Complete Docker guide with production examples
• Roadmap - Planned features and version history
• Changelog - Detailed release notes

Available Tools

Category	Tools
Discovery	fm_odata_list_tables, fm_odata_get_metadata, fm_odata_get_service_document
Queries	fm_odata_query_records, fm_odata_get_record, fm_odata_get_records, fm_odata_count_records
CRUD	fm_odata_create_record, fm_odata_update_record, fm_odata_delete_record
FM 2024/2025+	fm_odata_aggregate, fm_odata_cast, fm_odata_build_filter
Connection	fm_odata_connect, fm_odata_connect_multi, fm_odata_set_connection, fm_odata_list_connections, fm_odata_get_current_connection
Sessions	fm_odata_list_active_sessions, fm_odata_describe_sessions
Diagnostics	fm_odata_get_server_version
Config	fm_odata_config_add_connection, fm_odata_config_remove_connection, fm_odata_config_list_connections, fm_odata_config_get_connection, fm_odata_config_set_default_connection
Schema (DDL)	fm_odata_create_table, fm_odata_add_fields, fm_odata_delete_table, fm_odata_delete_field, fm_odata_create_index, fm_odata_delete_index

The FM 2024/2025+ tools are connection-free expression builders. fm_odata_cast and fm_odata_build_filter require FileMaker Server v21.1+ (FileMaker 2024); fm_odata_aggregate requires FileMaker Server v22.0.1+ (FileMaker 2025).

All connection-dependent OData tools (including the 6 schema DDL tools when enabled) accept an optional connection parameter to target a specific session without changing the active connection. Useful in multi-file solutions.

fm_odata_get_server_version detects the connected FileMaker Server version from $metadata (cached per session) and returns a feature-compatibility report covering basic_odata, cast, build_filter, aggregate, and metadata_comments (v26+). On servers that do not support server-side $apply, fm_odata_aggregate automatically falls back to client-side computation (capped at 10 000 records) with a [Compatibility] advisory.

The Schema (DDL) tools are hidden by default. Set FM_ALLOW_SCHEMA_EDITS=true to register them. See Schema Editing below.

Requirements

• Node.js 18.0.0 or higher
• FileMaker Server with OData API enabled
• FileMaker Account with appropriate access privileges

Environment Variables

FileMaker Connection

Variable	Description	Required	Default
FM_SERVER	FileMaker Server URL	Yes	-
FM_DATABASE	Database name	Yes	-
FM_USER	Username	Yes	-
FM_PASSWORD	Password	Yes	-
FM_VERIFY_SSL	Verify SSL certificates	No	true
FM_TIMEOUT	Request timeout (ms)	No	30000
FM_ALLOW_SCHEMA_EDITS	Enable schema (DDL) tools	No	false

HTTP/HTTPS Transport

Variable	Description	Required	Default
MCP_TRANSPORT	Transport type: stdio, http, or https	No	stdio
MCP_PORT	Port for HTTP/HTTPS server	No	3333 (HTTP), 3443 (HTTPS)
MCP_HOST	Host to bind to	No	localhost
MCP_CERT_PATH	Path to SSL certificate (HTTPS only)	No	-
MCP_KEY_PATH	Path to SSL private key (HTTPS only)	No	-

OData Query Syntax

The server supports OData 4.01 query options:

$filter   - Filter records (e.g., "Age gt 18")
$select   - Select specific fields
$orderby  - Sort results
$top      - Limit results
$skip     - Skip records (pagination)
$expand   - Include related records
$count    - Include total count
$apply    - Server-side aggregation (FileMaker Server v22.0.1+ / FileMaker 2025)

Example prompts:

Get contacts where Age is greater than 18

Show only Name and Email fields from Contacts

Sort contacts by LastName in descending order

Get the first 10 contacts, skip the first 20

FileMaker 2025 Advanced Features

Three additional tools provide expression-builder helpers for newer FileMaker Server capabilities. They require no active connection and return strings ready to use in the standard query tools.

fm_odata_aggregate — server-side aggregation (FileMaker Server v22.0.1+ / FileMaker 2025):

Sum invoice amounts grouped by customer:
  table=Invoices, method=sum, field=Amount, alias=Total, groupBy=["Customer"]

Count open cases per user:
  table=Cases, method=count, alias=OpenCount, filter="Status eq 'Open'", groupBy=["AssignedTo"]

fm_odata_cast — server-side type coercion (FileMaker Server v21.1+ / FileMaker 2024):

Return StartDate as a number for arithmetic:
  fields=[{field:"StartDate", type:"Int64"}], context="select"
  → use result as $select value in fm_odata_query_records

Cast Amount to String for text comparison in a filter:
  fields=[{field:"Amount", type:"String"}], context="filter"
  → embed result in a $filter expression: Amount/Edm.String eq '100'

fm_odata_build_filter — parameterized filter builder (FileMaker Server v21.1+ / FileMaker 2024):

Reusable filter with named placeholders:
  template="Title eq @title and Age gt @minAge",
  params={"@title":"Wizard of Oz","@minAge":18}
  → filter: "Title eq 'Wizard of Oz' and Age gt 18"

FileMaker 2026 Metadata Comments

FileMaker Server 2026 (v26) exposes table and field comments — including AI annotations — in the OData $metadata document. When connected to a v26+ server:

List tables with their comments:
  fm_odata_list_tables with includeDetails=true
  → contact — Contact table

Merged schema with field comments and AI annotations:
  fm_odata_describe_sessions
  → tables include `comment`; fields include `comment` and `aiAnnotation`

On v25 and older servers these options are ignored safely — call fm_odata_get_server_version first to check metadata_comments support.

Schema Editing (DDL)

FileMaker Server exposes a proprietary OData schema extension through the FileMaker_Tables and FileMaker_Indexes system endpoints. Six tools wrap it:

Tool	Operation
fm_odata_create_table	Create a table with field definitions
fm_odata_add_fields	Add fields to an existing table
fm_odata_delete_table	Delete a table and ALL its records
fm_odata_delete_field	Delete a field and all its data
fm_odata_create_index	Create an index on a field
fm_odata_delete_index	Delete a field index (no data loss)

Safety model:

• The tools are not registered unless the environment variable FM_ALLOW_SCHEMA_EDITS=true is set on the MCP server.
• fm_odata_delete_table and fm_odata_delete_field are irreversible and require an explicit confirm: true argument; without it they refuse and describe what would be deleted.
• The FileMaker account needs full access (schema modification) privileges. Claris recommends a dedicated account for table deletion.

Field definitions use SQL-style types: NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR(n), BLOB, etc. Repetitions in brackets (INT[4]). Optional flags: primary, unique, global, nullable, default (keyword such as CURRENT_USER or CURRENT_TIMESTAMP), and externalSecurePath for container fields.

Create a Company table:
  tableName="Company", fields=[
    {name:"Company ID", type:"int", primary:true},
    {name:"Company Name", type:"varchar(100)", nullable:false},
    {name:"Notes", type:"varchar(2000)", global:true}
  ]

Add a phone field:
  table="Company", fields=[{name:"Phone", type:"varchar(25)"}]

Index the State field:
  table="Company", field="State"

Limitations: relationships, layouts, scripts, value lists, and calculation/summary fields cannot be created via OData — only base tables, regular fields, and indexes.

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for detailed release notes.

---

Made with for the FileMaker and AI communities