FMO MCP Server¶

Overview¶

The FMO MCP (Model Context Protocol) server enables AI assistants to interact with your entity database. This allows for natural language queries, automated entity management, and intelligent file organization.

Quick Start¶

Option 1: Run from CLI¶

pnpm mcp-server --db /path/to/database.sqlite3 --system-db /path/to/system.sqlite3

Option 2: Run from App¶

Select a database in the FMO app
Navigate to System → MCP Server
Click "Start Server"
Server runs on http://127.0.0.1:3282/mcp

Option 3: Automatic via MCP Client¶

Some clients (like Claude Code) can start the server automatically when configured.

CLI Options¶

pnpm mcp-server [options]

Options:
  -d, --db <path>              Path to entities database file
  -s, --system-db <path>       Path to system database file (required)
  -p, --port <port>           HTTP port (default: 3282)
  -h, --host <host>           Host address (default: 127.0.0.1)
  --help                       Display help

Server Details¶

Transport: Streamable HTTP
Default URL: http://127.0.0.1:3282/mcp
Protocol: Model Context Protocol v1
Supported Clients: Claude Code, Claude Desktop, Cursor, Windsurf

Client Configuration¶

Claude Code¶

Claude Code supports HTTP transport natively. Add to your MCP configuration:

Project-level (.mcp.json in project directory):

{
  "mcpServers": {
    "clrmo-fmo": {
      "type": "http",
      "url": "http://127.0.0.1:3282/mcp"
    }
  }
}

User-level (~/.claude/mcp.json):

{
  "mcpServers": {
    "clrmo-fmo": {
      "type": "http",
      "url": "http://127.0.0.1:3282/mcp"
    }
  }
}

Claude Desktop¶

Claude Desktop only supports stdio transport. Use the bundled mcp-proxy binary:

Step 1: Start the FMO MCP server (either from app or CLI)

Step 2: Copy the config from the MCP Server panel in FMO (it includes the correct path)

Step 3: Add to Claude Desktop config:

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

{
  "mcpServers": {
    "clrmo-fmo": {
      "command": "<path_from_fmo_panel>/mcp-proxy.exe",
      "args": ["--url", "http://127.0.0.1:3282/mcp"]
    }
  }
}

Replace <path_from_fmo_panel> with the actual path shown in FMO's MCP Server panel.

Cursor / Windsurf¶

These clients may support HTTP transport. Try HTTP first:

{
  "mcpServers": {
    "clrmo-fmo": {
      "type": "http",
      "url": "http://127.0.0.1:3282/mcp"
    }
  }
}

If HTTP doesn't work, use the proxy binary approach (same as Claude Desktop).

mcp-proxy Binary¶

The proxy is a small Rust binary that bridges stdio MCP to the HTTP server:

Retry logic: Retries connection for up to 60 seconds
Platforms: Linux and Windows pre-built; macOS needs manual build

MCP Tools¶

The FMO MCP server provides the following tools:

Query Tools¶

`query_entities`¶

Search entities using custom query syntax.

{
  "name": "query_entities",
  "description": "Search entities with custom query syntax",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Query string (e.g., 'rock & 2024')"
      },
      "limit": {
        "type": "number",
        "description": "Maximum results to return (default: 100)"
      },
      "offset": {
        "type": "number",
        "description": "Offset for pagination (default: 0)"
      }
    }
  }
}

Example usage:

Find all rock songs from 2024:
query_entities(query="rock & 2024")

Find high-rated songs:
query_entities(query="@rating:>=4")

Find by filename:
query_entities(query="~holiday")

`get_entity`¶

Get details for a single entity by ID.

{
  "name": "get_entity",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Entity ID"
      }
    },
    "required": ["id"]
  }
}

`get_entities`¶

Get details for multiple entities by IDs.

{
  "name": "get_entities",
  "inputSchema": {
    "type": "object",
    "properties": {
      "ids": {
        "type": "array",
        "items": { "type": "number" },
        "description": "Array of entity IDs"
      }
    },
    "required": ["ids"]
  }
}

`get_entity_by_path`¶

Look up an entity by its file path.

{
  "name": "get_entity_by_path",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path to search for"
      }
    },
    "required": ["path"]
  }
}

`browse_entities`¶

Browse all entities with pagination.

{
  "name": "browse_entities",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "number",
        "description": "Results per page (default: 50)"
      },
      "offset": {
        "type": "number",
        "description": "Page offset (default: 0)"
      }
    }
  }
}

CRUD Tools¶

`add_entity`¶

Add a new entity to the database.

{
  "name": "add_entity",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path (required)"
      },
      "name": {
        "type": "string",
        "description": "Display name"
      },
      "attributes": {
        "type": "object",
        "description": "Key-value attributes"
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Tags to add"
      }
    },
    "required": ["path"]
  }
}

Example:

add_entity(
  path="/music/new-song.mp3",
  name="New Song",
  attributes={year: 2024, artist: "Artist Name"},
  tags=["rock", "2024", "new"]
)

`update_entity`¶

Update an existing entity.

{
  "name": "update_entity",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Entity ID (required)"
      },
      "name": {
        "type": "string",
        "description": "Display name"
      },
      "description": {
        "type": "string",
        "description": "Entity description"
      },
      "attributes": {
        "type": "object",
        "description": "Attributes to set (replaces all)"
      },
      "add_attributes": {
        "type": "object",
        "description": "Attributes to add (merges)"
      },
      "remove_attributes": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Attribute keys to remove"
      }
    },
    "required": ["id"]
  }
}

`delete_entity`¶

Delete an entity by ID.

{
  "name": "delete_entity",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Entity ID to delete"
      }
    },
    "required": ["id"]
  }
}

Tag Tools¶

`add_tags`¶

Add tags to an entity.

{
  "name": "add_tags",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Entity ID"
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Tags to add"
      }
    },
    "required": ["id", "tags"]
  }
}

`replace_tags`¶

Replace all tags on an entity.

{
  "name": "replace_tags",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Entity ID"
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "description": "New tags (replaces all existing)"
      }
    },
    "required": ["id", "tags"]
  }
}

`get_tags`¶

List all tags in the database.

{
  "name": "get_tags",
  "description": "Get all tags with usage counts",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "number",
        "description": "Maximum tags to return"
      }
    }
  }
}

Variable Tools¶

`get_variables`¶

Get all database variables.

{
  "name": "get_variables",
  "description": "Get all variables for current database",
  "inputSchema": {
    "type": "object"
  }
}

`get_variable`¶

Get a specific variable.

{
  "name": "get_variable",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Variable name"
      }
    },
    "required": ["name"]
  }
}

`set_variable`¶

Set a database variable.

{
  "name": "set_variable",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Variable name"
      },
      "value": {
        "description": "Variable value (any JSON type)"
      }
    },
    "required": ["name", "value"]
  }
}

Database Management Tools¶

`list_databases`¶

List all available databases.

{
  "name": "list_databases",
  "description": "Get list of all databases"
}

`select_database`¶

Set the active database.

{
  "name": "select_database",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Database ID"
      }
    },
    "required": ["id"]
  }
}

`get_current_database`¶

Get the currently active database.

{
  "name": "get_current_database",
  "description": "Get info about current database"
}

`get_system_db`¶

Get system database information.

{
  "name": "get_system_db",
  "description": "Get system database path"
}

Query Syntax Reference¶

The query_entities tool uses FMO's custom query syntax:

Syntax	Description	Example
`tagname`	Entities with tag	`rock`
`tag1 & tag2`	AND - both tags	`rock & 2024`
`tag1 \| tag2`	OR - either tag	`rock \| metal`
`-tag`	NOT - without tag	`-pop`
`@key:value`	Attribute equals	`@year:2024`
`@key:>value`	Greater than	`@rating:>4`
`@key:value1-value2`	Range	`@year:2020-2024`
`~text`	Path search	`~holiday`
`"tag with spaces"`	Spaces in tag	`"dead kennedys"`

Examples: - rock & 2024 - Rock music from 2024 - @rating:>=4 & ~*.mp3 - High-rated MP3s - "dead kennedys" & punk & -live - Studio Dead Kennedys tracks - @duration:<180 & @bpm:>140 - Short, fast tracks

Use Cases¶

Natural Language Search¶

Use AI to translate natural language to FMO queries:

User: "Show me all rock songs from 2024 that are rated 4 or higher"

AI: query_entities(query="rock & 2024 & @rating:>=4")

Automated Tagging¶

Let AI automatically tag entities:

User: "Tag these files based on their content"

AI:
1. get_entities(ids=[1, 2, 3])
2. Analyze file content
3. add_tags(id=1, tags=["rock", "energetic"])
4. add_tags(id=2, tags=["electronic", "ambient"])
5. add_tags(id=3, tags=["pop", "catchy"])

Smart Organization¶

Use AI to organize your database:

User: "Find duplicate entities and merge them"

AI:
1. query_entities(query="@size:1024-10240")  # Small files
2. Get MD5 checksums
3. Identify duplicates
4. Delete duplicates, keep originals

Batch Operations¶

Perform bulk operations via AI:

User: "Add 'favorite' tag to all 2024 entities"

AI:
1. query_entities(query="2024")
2. For each result: add_tags(id, ["favorite"])

Troubleshooting¶

Connection Refused¶

Problem: Client can't connect to server

Solutions: 1. Verify server is running (check FMO MCP Server panel) 2. Check port is correct (default: 3282) 3. Verify URL format: http://127.0.0.1:3282/mcp

Proxy Not Starting¶

Problem: mcp-proxy binary fails to start

Solutions: 1. Check binary path is correct 2. Verify binary is executable 3. Try HTTP transport instead (Claude Code) 4. Build proxy manually: pnpm build:proxy

Database Not Found¶

Problem: "No database selected" error

Solutions: 1. Use CLI with --db parameter 2. Or use FMO app to select database first 3. Verify database path is correct

Wrong Database¶

Problem: AI is querying wrong database

Solutions: 1. Use list_databases to see available databases 2. Use select_database(id) to choose correct one 3. Verify with get_current_database

Advanced¶

Server Logs¶

View server logs for debugging:

# Server logs to console
pnpm mcp-server --db /path/to/db.sqlite3

Custom Port¶

Run server on different port:

pnpm mcp-server --db /path/to/db.sqlite3 --port 3000

Update client config to match:

{
  "url": "http://127.0.0.1:3000/mcp"
}

Links¶

Overview - Introduction to FMO
Features - Detailed feature documentation
Pages - UI pages reference
Components - UI component screenshots and selectors