# Fms Odata Mcp

> Model Context Protocol (MCP) server for FileMaker Server OData 4.01 API integration

- **Type:** MCP server
- **Install:** `agentstack add mcp-fsans-fms-odata-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fsans](https://agentstack.voostack.com/s/fsans)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fsans](https://github.com/fsans)
- **Source:** https://github.com/fsans/fms-odata-mcp

## Install

```sh
agentstack add mcp-fsans-fms-odata-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# FileMaker Server OData MCP

[](https://www.npmjs.com/package/fms-odata-mcp)
[](https://opensource.org/licenses/MIT)

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

```bash
# Via NPM (recommended)
npm install -g fms-odata-mcp

# Or local development
git clone https://github.com/fsans/fms-odata-mcp.git
cd fms-odata-mcp
npm install
npm run build
```

> **Note:** This package was previously published as `filemaker-odata-mcp`. It has been
> renamed to `fms-odata-mcp` to align with the related `fms-*` repositories
> (`fms-odata-js`, `fms-odata-spec`). The old name is deprecated on npm; update your
> installs to `fms-odata-mcp`.

## 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:**

```json
{
  "mcpServers": {
    "filemaker-odata": {
      "command": "npx",
      "args": ["-y", "fms-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.

3. **For self-signed SSL certificates**, set `FM_VERIFY_SSL` to `"false"`

4. **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:

```bash
# 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
fms-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

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

#### HTTPS Mode

```bash
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:**

```python
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:**

```javascript
// 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:

```bash
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

```bash
# Clone and build
git clone https://github.com/fsans/fms-odata-mcp.git
cd fms-odata-mcp
npm run build
docker build -t fms-odata-mcp:latest .

# Run the container
docker run -d \
  --name fms-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 \
  fms-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:**

```bash
git clone https://github.com/fsans/fms-odata-mcp.git
cd fms-odata-mcp
npm run build
```

2. **Configure environment:**

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

3. **Start the server:**

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

#### Option D: Docker Compose with HTTPS

```bash
# 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:

```bash
curl http://localhost:3333/health
```

### 4. Dify Integration

To use this server as an MCP tool in [Dify](https://dify.ai):

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:

```text
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](./dev_stuf/QUICK_REFERENCE.md)** - One-page setup guide
- **[Prompt Examples](./dev_stuf/CLAUDE_DESKTOP_PROMPTS.md)** - Complete prompt reference
- **[Claude Desktop Setup](./dev_stuf/CLAUDE_DESKTOP_SETUP.md)** - Detailed configuration
- **[Docker Deployment](./DOCKER.md)** - Complete Docker guide with production examples
- **[Roadmap](./ROADMAP.md)** - Planned features and version history
- **[Changelog](./CHANGELOG.md)** - 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](#schema-editing-ddl) 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:

```text
$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:**

```text
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):

```text
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):

```text
Return StartDate as a number for arithmetic:
  field

…

## Source & license

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

- **Author:** [fsans](https://github.com/fsans)
- **Source:** [fsans/fms-odata-mcp](https://github.com/fsans/fms-odata-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fsans-fms-odata-mcp
- Seller: https://agentstack.voostack.com/s/fsans
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.