MCP-NixOS for VS Code: Setup & Config

What you can do with MCP-NixOS in VS Code

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

• Verify package names before proposing a Nix configuration.
• Locate historical package versions and their nixpkgs commit hashes.

Before you start: MCP-NixOS in VS Code

• 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 VS Code configuration

1. Choose VS Code configuration scope

   For MCP-NixOS, open Workspace: .vscode/mcp.json. Merge into servers; preserve existing inputs.

2. Add MCP-NixOS to VS Code

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

3. Check MCP-NixOS in VS Code

   MCP-NixOS: Start in VS Code’s MCP controls; inspect output and trust prompts.

{
  "servers": {
    "mcp-nixos": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-nixos"
      ],
      "env": {}
    }
  }
}

MCP-NixOS tools available to VS Code

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

nix

Look for nix among VS Code's agent-mode tools after starting MCP-NixOS through the MCP controls.

Query Nix packages, options, docs, functions, flakes, channels, cache status, and local flake inputs.

nix_versions

Look for nix_versions among VS Code's agent-mode tools after starting MCP-NixOS through the MCP controls.

MCP-NixOS: full stored tool descriptions

Troubleshooting MCP-NixOS in VS Code

• Make uvx mcp-nixos (from uv, for Python tools) available in the workspace, container, or remote environment hosting MCP-NixOS. Start through VS Code's MCP controls; inspect output and trust prompts.
• MCP-NixOS uses stdio here: VS Code 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 VS Code troubleshooting lives in the /clients/vscode guide.

Frequently asked questions