1. Home
  2. MCP-NixOS
  3. MCP-NixOS for Windsurf: Setup & Config

Data as of

MCP-NixOS for Windsurf: Setup & Config

MCP-NixOS gives Windsurf live Nix ecosystem lookups instead of guessed package names and settings.

What you can do with MCP-NixOS in Windsurf

A compact two-tool interface for verified Nix ecosystem lookups and reproducible version references.

  • Find Home Manager, nix-darwin, or Nixvim options.
  • Check binary-cache availability or inspect local flake inputs.

Before you start: MCP-NixOS in Windsurf

  • Python 3.11 or later
  • uv with uvx
  • Network access to queried data sources
  • Nix only for local flake-input operations

The README recommends uvx and states that ordinary API lookups do not need Nix. Docker and Nix launch alternatives are provided. HTTP mode is optional through MCP_NIXOS_TRANSPORT and related settings; stdio is the default. No required environment variables are stated for this launch.

MCP-NixOS Windsurf configuration

  1. Choose Windsurf configuration scope

    For MCP-NixOS, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

  2. Add MCP-NixOS to Windsurf

    Use the mcp-nixos entry below in mcpServers. Keep MCP-NixOS's documented stdio connection fields and your other Windsurf entries.

  3. Check MCP-NixOS in Windsurf

    MCP-NixOS: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "mcp-nixos": {
      "command": "uvx",
      "args": [
        "mcp-nixos"
      ],
      "env": {}
    }
  }
}

MCP-NixOS tools available to Windsurf

MCP-NixOS's stored tool list documents 2 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

nix

After refreshing MCP-NixOS in Windsurf settings, check Cascade's tool list for nix.

nix_versions

After refreshing MCP-NixOS in Windsurf settings, check Cascade's tool list for nix_versions.

Find package release history with nixpkgs commits, attribute paths, platform details, and available metadata.

MCP-NixOS: full stored tool descriptions

Troubleshooting MCP-NixOS in Windsurf

  • Check uvx mcp-nixos (from uv, for Python tools) on the machine running Windsurf's MCP integration for MCP-NixOS; refresh MCP and inspect Cascade's tools.
  • MCP-NixOS uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Local flake-input exploration still requires Nix.
  • Known limitation: API-backed lookups depend on reachable external data sources.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

MCP-NixOS — details. Windsurf guide

Frequently asked questions

Windsurf reads MCP-NixOS under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's mcp-nixos example uses stdio.

MCP-NixOS's Windsurf configuration invokes uvx mcp-nixos (from uv, for Python tools).

MCP-NixOS's stored list contains 2 tools, including nix, nix_versions. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

The README requires it for exploring local flake inputs from the Nix store.

Yes. Version-history results include nixpkgs commit hashes and attribute paths, with platform and package metadata when available.