---
title: SMBAct MCP server for Claude Code, Cursor and Codex
description: SMBAct's local MCP server lets Claude Code, Cursor, Codex and other MCP clients list, tile, focus and close windows on macOS, Windows and Linux. Setup and tools.
canonical: https://smblob.com/products/smbact/ai-agents/mcp-server/
date: 2026-11-16
locale: en
---

# SMBAct MCP server for Claude Code, Cursor and Codex

> Markdown version of https://smblob.com/products/smbact/ai-agents/mcp-server/
> Same content as the HTML page without navigation, styling or scripts. Cite the HTML URL.
> Site structure and the full page list for agents: https://smblob.com/llms.txt

SMBAct's local MCP server lets Claude Code, Cursor, Codex and other MCP clients list, tile, focus and close windows on macOS, Windows and Linux. Setup and tools.

[SMBAct](https://smblob.com/products/smbact/) › [AI agents](https://smblob.com/products/smbact/ai-agents/) › MCP server

## SMBAct MCP server

SMBAct has a [Model Context Protocol](https://modelcontextprotocol.io) server built in. With it, AI assistants on your computer (Claude Code, Codex, Cursor, VS Code, Claude Desktop and any other MCP client) can list your windows and displays, put windows into SMBAct’s layouts, move them to another monitor, bring them to the front, minimize them and, if you allow it, close them.

It runs inside SMBAct, only while SMBAct is running, and listens on `127.0.0.1` only. It is **off until you turn it on**. For agents that read [Agent Skills](https://smblob.com/products/smbact/ai-agents/agent-skills/), our free skills add the know-how on top: what to check first, what never to touch, and how to report.

![Konsole on KDE Plasma: the request “Editor on the left two thirds, files and this terminal stacked on the right”, then list_windows and three window_action calls (bottom-right-sixth, first-two-thirds, top-right-sixth) and the answer](https://smblob.com/docs/smbact/ai-agents/agent-kde-transcript.webp)

Each line is a real tool call to SMBAct: one `list_windows`, then one `window_action` per window. Recorded on KDE Plasma 6 (Wayland).

## Turn it on

1. In SMBAct, open **MCP server** in the sidebar.
2. Turn on **Enable the MCP server**. The status line shows **Running:** with the address, `http://127.0.0.1:5057/mcp` by default. To use another port, type it under **Port** and press **Apply**.
3. Under **Access**, leave **Require an access token** on (recommended: without a token any program on this computer can call the tools). **Show** or **Copy** the token. **Regenerate…** makes a new one; clients set up with the old token stop working until you give them the new one.
4. Under **Tools**, choose what clients may change. `list_windows` and `list_displays` are always available; the switches are **Arrange windows**, **Focus windows**, **Minimize all** and **Close windows**. With **Ask me before closing anything** on, SMBAct asks you each time a client wants to close something.
5. Under **Connect a client**, copy the snippet for your client. **Recent calls** at the bottom of the page lists what clients asked for and how long each call took.

MCP tool calls need an active license or a running trial. Clients can connect without one, but every tool call is refused until then.

## Connect a client

`<token>` is the access token from the MCP server page. On macOS, `<cli>` is `/Applications/SMBAct.app/Contents/Resources/bin/smbact-cli`. SMBAct’s own **Connect a client** section shows the same snippets with your port and token filled in.

### Claude Code

Over HTTP (any OS); add `--scope user` to use it in every project:

```bash
claude mcp add --transport http smbact http://127.0.0.1:5057/mcp --header "Authorization: Bearer <token>"
```

On macOS, as a local stdio server without port or token:

```bash
claude mcp add smbact -- <cli> mcp serve
```

### Cursor, VS Code and other `.mcp.json` clients

```json
{"mcpServers": {"smbact": {"type": "http", "url": "http://127.0.0.1:5057/mcp", "headers": {"Authorization": "Bearer <token>"}}}}
```

On macOS over stdio: `{"mcpServers": {"smbact": {"command": "<cli>", "args": ["mcp", "serve"]}}}`.

### OpenAI Codex

In `~/.codex/config.toml` (macOS, stdio):

```toml
[mcp_servers.smbact]
command = "<cli>"
args = ["mcp", "serve"]
```

### Claude Desktop

Settings › Developer › Edit Config (`claude_desktop_config.json`), then restart Claude Desktop. Over HTTP it goes through `mcp-remote`, which needs Node.js:

```json
{"mcpServers": {"smbact": {"command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:5057/mcp", "--header", "Authorization:${SMBACT_AUTH}"], "env": {"SMBACT_AUTH": "Bearer <token>"}}}}
```

On macOS, stdio works without Node.js: `{"mcpServers": {"smbact": {"command": "<cli>", "args": ["mcp", "serve"]}}}`.

The [Claude Code plugin](https://smblob.com/products/smbact/ai-agents/agent-skills/#install) connects the server for you on macOS, together with the skills.

## On macOS, Windows and Linux

- **macOS MCP server** (Apple Silicon, Intel): `smbact-cli` ships inside SMBAct and serves the same tools over stdio, with no port and no token; HTTP works too. In a terminal, `smbact-cli mcp status`, `config`, `token` and `snippets` show and change the server settings. SMBAct needs the Accessibility permission ([install guide](https://smblob.com/products/smbact/documentation/install-macos/)).
- **Windows MCP server** (x64): clients such as Claude Code, Claude Desktop, Cursor and Codex connect over HTTP to `127.0.0.1:5057` with the token. SMBAct listens on loopback only, so Windows Firewall has nothing to ask ([install guide](https://smblob.com/products/smbact/documentation/install-windows/)).
- **Linux MCP server** (x64): HTTP with the token, on X11 and on GNOME and KDE Plasma Wayland sessions. On Wayland SMBAct sees and moves every window through its [GNOME Shell extension](https://smblob.com/products/smbact/documentation/gnome-wayland/) or [KWin script](https://smblob.com/products/smbact/documentation/kde-plasma-wayland/), which [`wmctrl` and `xdotool` cannot do there](https://smblob.com/products/smbact/documentation/xdotool-wmctrl-wayland/).

`smbact-cli` for Windows and Linux is on the [roadmap](https://smblob.com/products/smbact/roadmap/); until then, use the HTTP connection there. It offers the same tools.

## Tools

SMBAct 2.0.0 has six tools. The next SMBAct update adds eight more, for exact placement, macOS desktops and version checks.

|Tool|What it does|In 2.0.0|
|-|-|-|
|`list_windows`|Open windows: id, app, title, frame, display, minimized / maximized / fullscreen, active; filter by app or title. SMBAct’s own windows are left out|✓|
|`list_displays`|Displays: index, name, main, frame, visible frame (without menu bar, Dock or taskbar), scale|✓|
|`window_action`|One of 46 SMBAct actions, as its hotkey would do it: halves, thirds, fourths, quarters, sixths, eighths, center, move to an edge, maximize, maximize height, fullscreen, minimize, restore, next or previous display|✓|
|`focus_window`|Un-minimizes a window if needed and brings it to the front|✓|
|`minimize_all`|Minimizes the windows of all displays, the active one or the main one (excluded apps are skipped)|✓|
|`close_window`|Closes a window, or every window of its application, like the close button (apps may ask to save). Off by default|✓|
|`place_windows`, `set_window_frame`|One to 32 windows at exact sizes: pixels, percent, fractions, anchors, grids, gaps, a dry run, a result per window|next update|
|`move_window_to_display`, `get_window`|Send a window to a named monitor; read one window|next update|
|`list_desktops`, `move_window_to_desktop`|macOS desktops (Spaces): list them, send a window to another one|next update|
|`get_capabilities`, `get_version`|What this SMBAct supports, and its version; answer without a license|next update|

A window is addressed by the id `list_windows` returns, or by `"active"` for the frontmost window. The frontmost window is usually the agent’s own terminal, so a client should list first. Errors come back as tool results with a code such as `license_required`, `tool_unavailable` or `window_not_found`.

## Built-in guard rails

![Seven guard rails: 127.0.0.1 only; Host and Origin checks refuse web pages; access token; license or trial; tool switches; excluded apps and SMBAct's own windows; close confirmation](https://smblob.com/docs/smbact/ai-agents/mcp-guards.webp)

- **Local only.** The server listens on `127.0.0.1`: other computers cannot reach it, and requests from web pages are refused.
- **Token.** Clients send `Authorization: Bearer <token>`. The snippets on the page hide the token; **Copy** copies the full text.
- **Your switches.** Listing is always allowed; arranging, focusing, minimizing and closing are separate switches. Closing is off by default and, when on, SMBAct asks you first. The dialog names the window, or says that all windows of the application would close.
- **Excluded apps.** An app excluded on SMBAct’s **Running Applications** page is out of reach for SMBAct’s hotkeys, the actions popup and MCP clients alike.

## See it on every platform

The same kind of request on Windows 10 and KDE Plasma 6 (Wayland). Every row in the client is a real tool call to SMBAct.

[![](https://smblob.com/docs/smbact/ai-agents/agent-win-poster.jpg)](https://files.smblob.com/smbact/ai-agents/agent-win.mp4)

Windows 10: a scripted MCP client in a console moves the terminal, Notepad++, Chrome and Explorer.

[![](https://smblob.com/docs/smbact/ai-agents/agent-kde-poster.jpg)](https://files.smblob.com/smbact/ai-agents/agent-kde.mp4)

KDE Plasma on Wayland: Kate to the first two thirds, Dolphin top right, the terminal under it. The macOS run is on the [AI agents page](https://smblob.com/products/smbact/ai-agents/).

## FAQ

**Is the SMBAct MCP server free?** It is part of SMBAct. Tool calls work during the 14-day trial and with a license (a one-time purchase from €14.99). Without either, clients can connect but tool calls are refused.

**Does it work on Windows and Linux?** Yes. On Windows and Linux clients connect over HTTP to `127.0.0.1:5057` with an access token. On macOS they can also use `smbact-cli mcp serve` over stdio, without a port or token.

**Does it work on Wayland?** Yes, on GNOME and KDE Plasma Wayland sessions, where `wmctrl` and `xdotool` cannot move windows. SMBAct sees and moves every window through its [GNOME Shell extension](https://smblob.com/products/smbact/documentation/gnome-wayland/) or [KWin script](https://smblob.com/products/smbact/documentation/kde-plasma-wayland/).

**Can the agent click buttons or type into apps?** No. The MCP server arranges windows: it lists, moves, resizes, focuses, minimizes and closes them. It does not launch apps, type, or read window content.

**Can other computers or web pages use the server?** No. It listens on `127.0.0.1` only, refuses requests from web pages, and asks for an access token by default.

## Read next

- [SMBAct agent skills](https://smblob.com/products/smbact/ai-agents/agent-skills/): make Claude Code, Codex, Cursor or Copilot use these tools carefully.
- [SMBAct for AI agents](https://smblob.com/products/smbact/ai-agents/): the overview, and which piece you need.
- [Download SMBAct](https://smblob.com/products/smbact/download/) · [Documentation](https://smblob.com/products/smbact/documentation/)

## Related

- HTML version of this page: https://smblob.com/products/smbact/ai-agents/mcp-server/
- Site map for agents: https://smblob.com/llms.txt
