MCP Directory

How to add Winx Code Agent to Claude Desktop

Native Rust MCP server giving coding agents a PTY-backed shell, file IO, and tree-sitter code navigation. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 30★ · stdio · no auth

Claude Desktop config for Winx Code Agent

cargo install winx-code-agent
{
  "mcpServers": {
    "winx-code-agent": {
      "command": "winx-code-agent",
      "args": [],
      "env": {
        "RUST_LOG": "winx_code_agent=info"
      }
    }
  }
}

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the Winx Code Agent config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm Winx Code Agent's tools appear under the 🔌 tools menu.

Before you start

  • Rust 1.75+ (via `cargo install winx-code-agent`)
  • Linux, macOS, or WSL2
  • A real terminal (Winx spawns its own PTY)

What Winx Code Agent can do in Claude Desktop

Initialize

Boots the workspace, picks the mode (wcgw/architect/code_writer), and hands back a thread_id. Must be called first or everything else errors out. With no workspace path it spins up a scratch playground; passing task_id_to_resume reopens a saved project root.

BashCommand

Runs commands, polls long-running ones, and drives TUIs. Supports is_background, status_check, send_text, send_specials, send_ascii, allow_multi, plus screen (a point-in-time TUI frame, with diff:true for changed lines only) and wait_for_turn. Reports the real exit code parsed from the prompt marker.

ReadFiles

Reads one or many files with line numbers; append :10-40 (or :10- / :-40) to a path for a range. When the token budget is hit it tells you the exact line and file:N-M syntax to resume from instead of dropping the tail.

FileWriteOrEdit

Full overwrites or forgiving SEARCH/REPLACE blocks (with optional @start-end line anchors). Validates read coverage and freshness, reports fuzzy tolerances applied, runs a tree-sitter syntax check across 18+ languages, and returns a compact diff of what changed.

MultiFileEdit

Edits several files all-or-nothing: every file's edit is validated and computed in memory first, and only if all succeed is anything written, so a failed SEARCH in the last file leaves the earlier ones untouched.

UndoEdit

Reverts a file to its content before the last FileWriteOrEdit/MultiFileEdit this session (per-file, last ~10 edits kept in memory). Refused if the file changed on disk since the edit; a brand-new file's creation isn't undoable.

ContextSave

Dumps a task description plus file globs into a single text file with workspace context, active files, and git status/diff for clean handoff and task resumption.

ReadImage

Returns a native MCP image content block (not base64 text) so multimodal models actually see the image. Confined to the workspace and size-capped.

Security

A local stdio MCP server with full shell/file access inside the workspace - same blast radius as letting the model into your terminal. Secret redaction is on by default (disable with WINX_NO_REDACT=1) and the PTY process group is killed on teardown. Use `architect` (read-only) or `code_writer` (allowlist) mode, or WINX_SANDBOX=1 (Linux Landlock) for a tighter leash. The optional HTTP transport (`winx serve --http`) puts arbitrary shell/file access on the network: it requires a bearer token, refuses to start without one, binds to loopback by default, and has a DNS-rebinding guard - but anyone with the token gets a shell on your machine, so keep it behind an authenticated tunnel.

Winx Code Agent + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Winx Code Agent config there under the "mcpServers" key and restart the client.

Is Winx Code Agent safe to use with Claude Desktop?

A local stdio MCP server with full shell/file access inside the workspace - same blast radius as letting the model into your terminal. Secret redaction is on by default (disable with WINX_NO_REDACT=1) and the PTY process group is killed on teardown. Use `architect` (read-only) or `code_writer` (allowlist) mode, or WINX_SANDBOX=1 (Linux Landlock) for a tighter leash. The optional HTTP transport (`winx serve --http`) puts arbitrary shell/file access on the network: it requires a bearer token, refuses to start without one, binds to loopback by default, and has a DNS-rebinding guard - but anyone with the token gets a shell on your machine, so keep it behind an authenticated tunnel.

How do I install and run it?

Run `cargo install winx-code-agent` (needs Rust 1.75+); the binary lands in ~/.cargo/bin. Add it to your client with a `mcpServers` entry using command `winx-code-agent`, or for Claude Code run `claude mcp add winx -- winx-code-agent`. The first tool call must always be Initialize.

What are the three workspace modes?

wcgw gives full shell and file access; architect is read-only (no writes, most commands disabled); code_writer lets you allowlist commands and write globs, enforced with tree-sitter so it checks every command on a line including pipelines, subshells, and command substitution.

Can a cloud client like ChatGPT use it?

Yes. Run `winx serve --http --bind 127.0.0.1:8000 --token <secret>` to serve MCP over Streamable HTTP at /mcp. Every request must carry the token as an Authorization: Bearer header; the server refuses to start without a token. Put a tunnel (e.g. cloudflared) in front and allow its hostname through the DNS-rebinding guard.

View repo Full Winx Code Agent page