QFloat Manual · 10 of 12
MCP and AI Assistants
Talk to QFloat from Claude, Cursor and other MCP apps through its built-in local MCP server: off by default, runs on your Mac with no network listener, setup snippets and every tool.
What it does #
QFloat has a built-in MCP server (Model Context Protocol). It lets an AI app on your Mac, like Claude Desktop, Claude Code or Cursor, read your QFloat library and, if you allow it, organize it for you: “make a group from my Projects folder”, “move the invoices to page 2”, “open the Northwind brief”.
Local only #
- The server runs on your Mac. The AI app starts QFloat as a local helper (
QFloat --mcp-stdio) and talks to it directly. There is no network listener, and nothing is sent to WithyWork. - It is off until you turn it on.
- A cloud-based AI app may send what it reads to its own service, under that app’s terms.
Turn it on #
Open Settings › MCP Server. Three switches, all off by default:
| Switch | Lets AI apps |
|---|---|
| Allow use | Connect, then list and search your groups and items. Off: nothing can connect, read or change anything. |
| Allow changes | Add items and groups (including a group made from a folder), rename, recolor, sort, move, and open items in QFloat. |
| Allow deleting | Remove items, groups and pages from QFloat. Your files on disk are never touched. |
The tab also has an MCP Activity list of recent calls.
Connect an AI app #
Settings › MCP Server has copy buttons for each app. QFloat never edits other apps’ settings files; you paste the snippet yourself.
Claude Desktop
In Claude, open Settings › Developer › Edit Config, paste the config into claude_desktop_config.json (merge into an existing mcpServers), save, then quit and reopen Claude.
{"mcpServers":{"qfloat":{"command":"/Applications/QFloat.app/Contents/MacOS/QFloat","args":["--mcp-stdio"]}}}Cursor
Settings › MCP › Add new global MCP server opens ~/.cursor/mcp.json. Paste the same config and save. Cursor shows qfloat with a green dot when it’s connected.
Claude Code
Run once in Terminal, then type /mcp in claude to check:
claude mcp add qfloat -- '/Applications/QFloat.app/Contents/MacOS/QFloat' --mcp-stdioAny other MCP app
Add a stdio server named qfloat. Command: /Applications/QFloat.app/Contents/MacOS/QFloat. Arguments: --mcp-stdio. Add --read-only to block changes for that app, whatever Settings allows.
With QFloat open or closed #
When QFloat is open, every request goes through the app, so there is only ever one copy of your library being edited, and opening items or granting a folder works. When it’s closed, the helper reads and edits the saved library directly. The switches always apply. Hidden items are left out of every tool.
Tools #
| Tool | Does |
|---|---|
library_summary | Counts of pages, groups and items, and whether the trial or Premium is active. |
pages_list | Every page, in order, with its groups. |
groups_list | Groups with subgroups and item counts. |
groups_get | One group with its items and subgroups. |
items_get | One item: title, kind, URL or path, status, group, last opened. |
items_search | Fuzzy search over titles, link hosts and paths. |
items_find | Find items by name across all pages. |
drives_list | Mounted drives with free space. |
items_add_link | Add a web link to a group. |
items_add_file | Add a folder, file or app by path. |
groups_create_from_path | Make a group from a folder’s contents. |
items_update | Rename an item or change a link’s URL. |
items_rename | Set or clear an item’s friendly name. |
items_move | Move items to a group or page. |
items_open | Open an item (needs QFloat open). |
items_set_color | Set items’ own color (Premium). |
groups_create | Create a group or subgroup (subgroups are Premium). |
groups_rename | Rename a group. |
groups_move_to_page | Move a group to a page. |
groups_set_sort | Set a group’s sort order. |
groups_set_collapsed | Collapse or expand a group. |
groups_set_color | Set a group’s color and scope (Premium). |
pages_create | Add a page (Premium). |
pages_rename | Rename a page. |
items_delete | Remove items (files are never touched). |
groups_delete | Delete a group (files are never touched). |
pages_delete | Delete a page; its groups move to page 1. |
Write tools need Allow changes; the three delete tools need Allow deleting too.