Floom MCP Sync

Lightweight MCP server for Floom skills. The launch path is CLI-first; MCP gives agents a small search/get/status/sync surface and keeps full skill content out of always-on context.

npx -y @floomhq/floom-mcp-sync

On startup it reads ~/.floom/config.json, fetches the signed-in user's sync set from /api/v1/me/skills, and writes native skill packages:

<skills-dir>/
  <slug>/
    SKILL.md
    references/
    examples/
    scripts/
    assets/

references/, examples/, scripts/, and assets/ are optional and only appear when the synced package includes supporting files. Search results stay compact. Full SKILL.md content loads only when an agent calls floom_get_skill or when local sync writes the package.

Setup

Claude Code:

{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": ["-y", "@floomhq/floom-mcp-sync"],
      "env": {
        "FLOOM_SKILLS_DIR": "~/.claude/skills"
      }
    }
  }
}

Codex:

[mcp_servers.floom]
command = "npx"
args = ["-y", "@floomhq/floom-mcp-sync"]

[mcp_servers.floom.env]
FLOOM_SKILLS_DIR = "~/.codex/skills"

Directory resolution order is FLOOM_SKILLS_DIR, CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, CURSOR_SKILLS_DIR, OPENCODE_SKILLS_DIR, KIMI_SKILLS_DIR, then ~/.claude/skills.

Sync Behavior

Sync stores a machine-local manifest next to the Floom CLI config at ~/.floom/sync-manifest.json. The manifest records each package file path, slug, SHA-256 hash, and sync time, which lets MCP detect unchanged files, missing files, local edits, and blocked paths.

Version 1 sync does not replace existing local files. Remote updates, existing untracked files, and locally edited tracked files are skipped as conflicts. Symlinks are never followed. Move or delete the local file to accept the Floom version on the next sync.

The poll uses HTTP If-None-Match against /api/v1/me/skills, so unchanged responses are 304 with no body. If a Floom-tracked local file is missing after a 304, MCP refetches once without the ETag so Version 1 can recreate missing files without overwriting existing files.

Configure the preview poll interval with FLOOM_SYNC_INTERVAL_MS (default 60000, minimum 10000).

Tools

• floom_search_skills(query, library?, type?, limit?) searches /api/v1/search and returns compact hits: slug, title, description, type, library placement, folder, and install URL.
• floom_get_skill(slug) fetches full skill content from /api/v1/skills/<slug> on demand.
• floom_status() reports the local manifest, tracked file counts, and drift counts.
• floom_sync() runs one foreground sync.

type is knowledge, instruction, workflow, or skill. limit is 1-50.

MCP does not expose the full library as context. It does not publish, mutate libraries, manage teams, or handle marketplace workflows.