SwiftList Manual · 17 of 19

MCP: use SwiftList with Claude, Codex and other AI assistants

SwiftList for Mac includes a small MCP server. MCP is the way AI apps such as Claude connect to other apps. With it, an assistant on your Mac can read your lists, and change them only if you allow it.

What it is, and what it isn’t #

• It is in the App Store version of SwiftList for Mac. There is no MCP on iPhone or iPad. An assistant on the Mac sees the same lists, and changes reach your other devices through iCloud Sync if you have Premium.
• It is off until you turn it on, and read-only until you turn on Allow changes.
• It runs only on your Mac. The AI app starts SwiftList as a helper and talks to it directly. There is no network connection and nothing is sent to WithyWork.
• A cloud-based AI app may send what it reads to its own service. That is between you and that app.

Step 1: turn it on in SwiftList #

1. Open SwiftList on your Mac and open Settings (⌘,).
2. Find the MCP Server section and turn on MCP server.
3. Leave Allow changes off if you only want the assistant to read. Turn it on to let it add, edit, check off, move and archive.
4. Turn on Allow deleting only if you want the assistant to be able to delete. Archiving doesn’t need it.
5. Look at Connect an AI app. It has ready-to-copy snippets with your Mac’s real app path.

What each switch allows #

Only the switches in SwiftList’s Settings grant anything. A setup line can take permission away, never add it: put --read-only after --mcp-stdio to keep one assistant read-only, or --no-deletes to stop it deleting.

The command #

Every AI app gets the same command and argument:

/Applications/SwiftList.app/Contents/MacOS/SwiftList --mcp-stdio

This assumes SwiftList is in your Applications folder. The snippets in Connect an AI app always show the right path for your Mac.

Claude Desktop #

Tested with SwiftList.

1. In Claude, open Settings, Developer, Edit Config. This opens ~/Library/Application Support/Claude/claude_desktop_config.json.
2. Add SwiftList under mcpServers. If the file already has other servers, add the "swiftlist" entry next to them, inside the same mcpServers braces.

   {
     "mcpServers": {
       "swiftlist": {
         "command": "/Applications/SwiftList.app/Contents/MacOS/SwiftList",
         "args": ["--mcp-stdio"]
       }
     }
   }

3. Save the file and quit Claude completely (⌘Q), then open it again.
4. Start a new chat. SwiftList’s tools appear under the tools or connectors menu in the message box.

Claude Cowork #

Cowork runs inside the Claude desktop app, which uses the same config file as above. Set up Claude Desktop first, restart Claude, then start a Cowork task and check whether SwiftList’s tools are listed.

We haven’t tested Cowork ourselves, and Anthropic’s own notes on local servers in Cowork have changed over time. If the tools don’t show in Cowork, use SwiftList from a regular Claude chat, which is tested.

Claude Code #

claude mcp add swiftlist -- /Applications/SwiftList.app/Contents/MacOS/SwiftList --mcp-stdio

OpenAI Codex #

This should work, since Codex speaks standard MCP over stdio, but we’ve tested with Claude Desktop, not Codex. Either run:

codex mcp add swiftlist -- /Applications/SwiftList.app/Contents/MacOS/SwiftList --mcp-stdio

or add this to ~/.codex/config.toml:

[mcp_servers.swiftlist]
command = "/Applications/SwiftList.app/Contents/MacOS/SwiftList"
args = ["--mcp-stdio"]

Run codex mcp list to check it is there, then start a new Codex session. The Codex app, CLI and IDE extension share this config.

Cursor #

Put the same JSON as Claude Desktop in ~/.cursor/mcp.json.

Grok Bot #

Grok Bot works from its own computer in the cloud, so it can’t start SwiftList’s helper the way Claude Desktop does. What does work: if you use the Grok Bot desktop app on your Mac and allow it to run commands there, Grok Bot can run the SwiftList helper on your Mac for each request. It isn’t a standing connection. Each request starts the helper, asks one question, and ends.

1. Turn on the MCP server in SwiftList, as in step 1.
2. Make sure the Grok Bot desktop app is open and your Mac is connected.
3. Save this small helper on your Mac, for example as ~/bin/swiftlist-mcp, and make it runnable with chmod +x ~/bin/swiftlist-mcp:

   #!/bin/sh
   # swiftlist-mcp TOOL [JSON-ARGUMENTS]
   # Starts SwiftList's MCP helper, calls one tool, prints the reply.
   APP="/Applications/SwiftList.app/Contents/MacOS/SwiftList"
   TOOL="$1"
   ARGS="${2:-}"
   [ -n "$ARGS" ] || ARGS='{}'
   printf '%s\n' \
     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
     "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":$ARGS}}" \
     | "$APP" --mcp-stdio

4. Ask Grok Bot something like: “On my Mac, run ~/bin/swiftlist-mcp lists_today and tell me what’s on today.” Grok Bot will ask you to approve running it on your Mac.

The same switches apply. If Allow changes is off, a change is refused. What Grok Bot reads goes to Grok Bot’s service, like any cloud assistant.

Other MCP apps #

Any MCP app that can start a local stdio server can use the same command. The helper speaks MCP over standard input and output, one JSON-RPC message per line.

Does SwiftList need to be open? #

• Open, with the MCP server on: the helper passes every request to the running app over a private local socket. You see changes in the window right away, alerts are updated, and iCloud Sync sends changes at once.
• Closed: the helper reads and writes your saved lists itself, one request at a time. Changes reach iCloud the next time you open SwiftList.
• Open but not answering: reads still work and changes are refused. Quit and reopen SwiftList.

The helper only touches SwiftList’s own data, inside its sandbox. SwiftList never edits an AI app’s config file. You paste the snippet yourself.

Tools #

44 tools: 16 read, 24 change and 4 delete. Assistants can name a list or item by its title, by a path like Groceries > Milk, or by the short #id shown in results. Dates can be 2026-10-12, 2026-10-12 14:30, today, tomorrow or now. A plain day means 9:00 for a start and 17:00 for a due date. none clears a date.

Read tools #

Available whenever the MCP server is on.

Change tools #

Need Allow changes.

Delete tools #

Need Allow deleting. Hidden otherwise.

Resources #

Apps that read MCP resources also get swiftlist://today, swiftlist://list/… for each top-level list (as Markdown), and swiftlist://capabilities.

Free limits still apply #

On Free, anything that would make a third level of nesting is refused with “Needs SwiftList Premium.” and nothing changes.

Example prompts #

• “What’s on my SwiftList today?”
• “Search SwiftList for anything about the dentist.”
• “Show me my Packing list with everything inside it.”
• “Make a SwiftList list called Garage Sale with these items, due Saturday.”
• “Check off Milk and Eggs in Groceries.”
• “Move the Weekend Reset list to next Saturday.”
• “Start the Workout template for tomorrow.”
• “How did I do last month? Use SwiftList Insights.”
• “Archive everything I finished more than 30 days ago.”

Privacy and safety #

• Start read-only. Turn on Allow changes when you trust the setup.
• Prefer archive over delete. Archived items can be restored from Settings, Archive.
• Settings, MCP Activity lists calls made through the running app, newest first. Calls answered while SwiftList was closed aren’t listed.
• Turning the MCP server off stops a running session at its next request.

Check that it works #

In Terminal, this should print SwiftList’s tool list:

APP="/Applications/SwiftList.app/Contents/MacOS/SwiftList"
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | "$APP" --mcp-stdio

Troubleshooting MCP #

SwiftList Direct #

We are also working on SwiftList Direct, a separate Mac version to be sold from withywork.com. Its MCP server can also be reached over HTTP on your own Mac while the app is open. It isn’t available yet. This page will cover it when it is.

For SwiftList 2.0. Updated October 11, 2026.