MCP-NixOS

Un servidor para buscar recursos de NixOS, Home Manager y nix-darwin.

GitHub

854

Documentación

MCP-NixOS - Porque tu IA no debería alucinar nombres de paquetes

CodeRabbit Pull Request Reviews

Inicio rápido

🚨 ¡No se requiere Nix/NixOS! Funciona en cualquier sistema: Windows, macOS, Linux. Solo estás consultando APIs.

Opción 1: uvx (Recomendado)

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

Opción 2: Nix

{
  "mcpServers": {
    "nixos": {
      "command": "nix",
      "args": ["run", "github:utensils/mcp-nixos", "--"]
    }
  }
}

Opción 3: Docker

{
  "mcpServers": {
    "nixos": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"]
    }
  }
}

Tu IA ahora tiene acceso a datos reales de NixOS en lugar de inventar cosas. De nada.

Opción 4: HTTP (MCP remoto)

FastMCP admite ejecutar este servidor a través de HTTP en una URL (el endpoint de MCP por defecto es /mcp).

# Run an HTTP MCP server at http://127.0.0.1:8000/mcp
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos

STDIO (por defecto):

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

Ruta personalizada:

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos

HTTP sin estado (desactiva el estado de sesión por cliente):

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

Opción 5: Agente de codificación Pi

Pi no habla MCP de forma nativa. Dos rutas compatibles:

A. pi-mcp-adapter (recomendado: habla MCP, fuente única de verdad):

pi install npm:pi-mcp-adapter

Luego añade a ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": ["mcp-nixos"],
      "lifecycle": "lazy"
    }
  }
}

B. Extensión local del proyecto (clonar + ejecutar): este repositorio incluye .pi/extensions/mcp-nixos.ts, que se carga automáticamente cuando ejecutas pi en el repositorio clonado. Opcional: cd .pi && npm install para la resolución del tipo de editor. Pi lo ejecuta de cualquier manera.

¿Qué es esto?

Un servidor MCP que proporciona información precisa y en tiempo real sobre:

Paquetes NixOS - Más de 130K paquetes que realmente existen
Opciones de NixOS - Más de 23K formas de configurar tu sistema
Home Manager - Más de 5K opciones para entusiastas de dotfiles
nix-darwin - Más de 1K configuraciones de macOS que Apple no documenta
Nixvim - Más de 5K opciones para configuración de Neovim a través de búsqueda de NuschtOS
NVF - Más de 2.4K opciones de Neovim de su documentación inestable publicada
FlakeHub - Más de 600 flakes del registro de FlakeHub.com
Noogle - Más de 2K funciones de Nix con firmas de tipos a través de noogle.dev
Wiki de NixOS - Documentación comunitaria y guías de wiki.nixos.org
nix.dev - Tutoriales y guías oficiales de Nix de nix.dev
Versiones de paquetes - Versiones históricas con hashes de commit a través de NixHub.io
Estado de caché binaria - Verifica si los paquetes están en caché en cache.nixos.org con tamaños de descarga
Entradas de flakes locales - Explora tus dependencias de flakes fijadas directamente desde el almacén de Nix (requiere Nix)

Las herramientas

Solo dos. Consolidamos 17 herramientas en 2 porque la ventana de contexto de tu IA no es infinita.

~1,030 tokens en total. Eso es todo. Mientras otros servidores MCP acaparan tu contexto como si fuera Black Friday, nosotros estamos tomando té minimalista en la esquina. Tu IA obtiene superpoderes de NixOS sin el peso.

`nix` - Herramienta de consulta unificada

Una herramienta para gobernarlos a todos:

nix(action, query, source, type, channel, limit, version, system)

version y system solo son utilizados por action="cache".

Acción	Qué hace
`search`	Buscar paquetes, opciones, programas o flakes
`info`	Obtener información detallada sobre un paquete u opción
`stats`	Obtener conteos y categorías
`browse`	Navegar por Home Manager, Darwin, Nixvim, NVF o Noogle por prefijo (alias heredado: `options`)
`channels`	Listar canales de NixOS disponibles
`flake-inputs`	Explorar entradas de flakes locales desde el almacén de Nix
`cache`	Verificar el estado de caché binaria para paquetes
`store`	Leer archivos o listar directorios en una ruta explícita de `/nix/store` (requiere Nix)

Fuente	Qué consulta
`nixos`	Paquetes, opciones, programas
`home-manager`	Opciones de Home Manager
`darwin`	Opciones de nix-darwin
`flakes`	Flakes comunitarios (search.nixos.org)
`flakehub`	Registro de FlakeHub (flakehub.com)
`nixvim`	Opciones de configuración de Neovim de Nixvim
`nvf`	Opciones de configuración de Neovim de NVF (documentación inestable más reciente)
`noogle`	Firmas de funciones y documentación de Nix (noogle.dev)
`wiki`	Artículos de la Wiki de NixOS (wiki.nixos.org)
`nix-dev`	Documentación oficial de Nix (nix.dev)
`nixhub`	Metadatos de paquetes y rutas de almacén (nixhub.io)

Los resultados de NVF utilizan rutas de opciones canónicas de vim.*. Las consultas también pueden usar la forma abreviada programs.nvf.vim.* o la ruta de módulo de NixOS/Home Manager programs.nvf.settings.vim.*; ambas se normalizan automáticamente.

Ejemplos:

# Search NixOS packages
nix(action="search", query="firefox", source="nixos", type="packages")

# Get package info
nix(action="info", query="firefox", source="nixos", type="package")

# Search Home Manager options
nix(action="search", query="git", source="home-manager")

# Browse darwin options
nix(action="browse", source="darwin", query="system.defaults")

# Search Nixvim options
nix(action="search", query="telescope", source="nixvim")

# Get Nixvim option info
nix(action="info", query="plugins.telescope.enable", source="nixvim")

# Search NVF options
nix(action="search", query="vim.languages.nix", source="nvf")

# Get NVF option info using a module wrapper path
nix(action="info", query="programs.nvf.settings.vim.languages.nix.enable", source="nvf")

# Browse NVF options below a prefix
nix(action="browse", query="programs.nvf.vim.languages.nix", source="nvf")

# Search FlakeHub
nix(action="search", query="nixpkgs", source="flakehub")

# Get FlakeHub flake info
nix(action="info", query="NixOS/nixpkgs", source="flakehub")

# Search Noogle for Nix functions
nix(action="search", query="mapAttrs", source="noogle")

# Get Noogle function info
nix(action="info", query="lib.attrsets.mapAttrs", source="noogle")

# Browse Noogle function categories
nix(action="browse", source="noogle", query="lib.strings")

# Search NixOS Wiki
nix(action="search", query="nvidia", source="wiki")

# Get Wiki page info
nix(action="info", query="Flakes", source="wiki")

# Search nix.dev documentation
nix(action="search", query="packaging tutorial", source="nix-dev")

# Search NixHub for package metadata
nix(action="search", query="nodejs", source="nixhub")

# Get detailed package info from NixHub (license, homepage, store paths)
nix(action="info", query="python", source="nixhub")

# Check binary cache status
nix(action="cache", query="hello")

# Check cache for specific version
nix(action="cache", query="python", version="3.12.0")

# Check cache for specific system
nix(action="cache", query="firefox", system="x86_64-linux")

# Get stats
nix(action="stats", source="nixos", channel="stable")

# List local flake inputs (requires Nix)
nix(action="flake-inputs", type="list")

# Browse files in a flake input
nix(action="flake-inputs", type="ls", query="nixpkgs:pkgs/by-name")

# Read a file from a flake input
nix(action="flake-inputs", type="read", query="nixpkgs:flake.nix")

# List or read a store path directly (requires Nix)
nix(action="store", type="ls", query="/nix/store/<hash>-<name>")
nix(action="store", type="read", query="/nix/store/<hash>-<name>/flake.nix")

`nix_versions` - Historial de versiones de paquetes

Encuentra versiones históricas con hashes de commit de nixpkgs. La salida incluye:

Metadatos del paquete (licencia, página de inicio, programas) cuando estén disponibles
Disponibilidad de plataforma por versión (Linux/macOS)
Hash de commit de nixpkgs para compilaciones reproducibles
Ruta de atributo para expresiones Nix

nix_versions(package, version, limit)

Ejemplos:

# List recent versions with metadata
nix_versions(package="python", limit=5)

# Find specific version
nix_versions(package="nodejs", version="20.0.0")

Instalación

NO necesitas Nix instalado. Esto se ejecuta en cualquier lugar donde se ejecute Python.

# Run directly (no install)
uvx mcp-nixos

# Or install
pip install mcp-nixos

Para usuarios de Nix:

nix run github:utensils/mcp-nixos
nix profile install github:utensils/mcp-nixos

Instalación declarativa (NixOS / Home Manager / nix-darwin)

mcp-nixos está disponible en nixpkgs:

# NixOS (configuration.nix)
environment.systemPackages = [ pkgs.mcp-nixos ];

# Home Manager (home.nix)
home.packages = [ pkgs.mcp-nixos ];

# nix-darwin (darwin-configuration.nix)
environment.systemPackages = [ pkgs.mcp-nixos ];

O usa el flake directamente con el overlay proporcionado:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    mcp-nixos.url = "github:utensils/mcp-nixos";
  };

  outputs = { self, nixpkgs, mcp-nixos, ... }: {
    # Example: NixOS configuration
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [{
        nixpkgs.overlays = [ mcp-nixos.overlays.default ];
        environment.systemPackages = [ pkgs.mcp-nixos ];
      }];
    };

    # Example: Home Manager standalone
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs {
        system = "x86_64-linux";
        overlays = [ mcp-nixos.overlays.default ];
      };
      modules = [{
        home.packages = [ pkgs.mcp-nixos ];
      }];
    };
  };
}

overlays.default solo añade pkgs.mcp-nixos. El paquete incluye su propia pila de FastMCP 4 / MCP SDK 2 (ver nix/fastmcp4.nix), incluyendo un starlette en o por encima del piso de seguridad 1.0.1 que FastMCP requiere, por lo que nada más en tu conjunto de paquetes de Python cambia, incluso en canales de nixpkgs que aún incluyen FastMCP 3. Si también deseas que pkgs.python3Packages.fastmcp en sí se actualice en todo el conjunto, aplica mcp-nixos.overlays.fastmcp4 adicionalmente.

Desarrollo

nix develop          # Enter dev shell
nix build            # Build package
pytest tests/        # Run tests
ruff check .         # Lint
ruff format .        # Format
mypy mcp_nixos/      # Type check

Agradecimientos

NixHub.io - Historial de versiones de paquetes
search.nixos.org - Búsqueda oficial de NixOS
FlakeHub - Registro de flakes de Determinate Systems
Jetify - Creadores de Devbox y NixHub
Noogle - Motor de búsqueda de funciones de Nix
NuschtOS - Infraestructura de búsqueda de opciones estáticas que impulsa el soporte de Nixvim
Nixvim - Marco de configuración de Neovim para Nix
NVF - Marco de configuración de Neovim y catálogo de opciones publicado

Licencia

MIT - Porque compartir es cuidar.

Creado por James Brink. Mantenido por mas̶o̶c̶h̶i̶s̶t̶a̶s̶ entusiastas que disfrutan de Nix.