MCP-NixOS

Um servidor para pesquisar recursos do NixOS, Home Manager e nix-dar

Documentação

MCP-NixOS — Porque Sua IA Não Deveria Alucinar Nomes de Pacotes

CodeRabbit Pull Request Reviews

Início Rápido

🚨 Nix/NixOS Não é Necessário! Funciona em qualquer sistema — Windows, macOS, Linux. Você está apenas consultando APIs.

Opção 1: uvx (Recomendado)

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

Opção 2: Nix

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

Opção 3: Docker

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

Sua IA agora tem acesso a dados reais do NixOS em vez de inventar coisas. De nada.

Opção 4: HTTP (MCP Remoto)

FastMCP suporta executar este servidor via HTTP em uma URL (o endpoint MCP padrão é /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 (padrão):

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

Caminho personalizado:

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

HTTP sem estado (desativa o estado de sessão por cliente):

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

Opção 5: Agente de Codificação Pi

Pi não fala MCP nativamente. Dois caminhos suportados:

A. pi-mcp-adapter (recomendado — fala MCP, fonte única de verdade):

pi install npm:pi-mcp-adapter

Depois adicione a ~/.pi/agent/mcp.json:

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

B. Extensão local do projeto (clone + execute): este repositório inclui .pi/extensions/mcp-nixos.ts, carregado automaticamente quando você executa pi no repositório clonado. Opcional: cd .pi && npm install para resolução do tipo de editor. O Pi executa de qualquer forma.

O Que É Isso?

Um servidor MCP que fornece informações precisas e em tempo real sobre:

Pacotes NixOS — 130 mil+ pacotes que realmente existem
Opções NixOS — 23 mil+ formas de configurar seu sistema
Home Manager — 5 mil+ opções para entusiastas de dotfiles
nix-darwin — 1 mil+ configurações do macOS que a Apple não documenta
Nixvim — 5 mil+ opções para configuração do Neovim via busca NuschtOS
NVF — 2,4 mil+ opções do Neovim a partir da sua documentação instável publicada
FlakeHub — 600+ flakes do registro FlakeHub.com
Noogle — 2 mil+ funções Nix com assinaturas de tipo via noogle.dev
Wiki NixOS — Documentação e guias da comunidade em wiki.nixos.org
nix.dev — Tutoriais e guias oficiais do Nix em nix.dev
Versões de pacotes — Versões históricas com hashes de commit via NixHub.io
Status do cache binário — Verifique se os pacotes estão em cache em cache.nixos.org com tamanhos de download
Entradas locais de flakes — Explore suas dependências fixadas de flakes diretamente do store do Nix (requer Nix)

As Ferramentas

Apenas duas. Consolidamos 17 ferramentas em 2 porque a janela de contexto da sua IA não é infinita.

~1.030 tokens no total. É isso. Enquanto outros servidores MCP estão monopolizando seu contexto como se fosse Black Friday, nós estamos tomando chá minimalista no canto. Sua IA ganha superpoderes NixOS sem o inchaço.

`nix` — Ferramenta de Consulta Unificada

Uma ferramenta para governar todas:

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

version e system são usados apenas por action="cache".

Ação	O que faz
`search`	Busca pacotes, opções, programas ou flakes
`info`	Obtém informações detalhadas sobre um pacote ou opção
`stats`	Obtém contagens e categorias
`browse`	Navega por Home Manager, Darwin, Nixvim, NVF ou Noogle por prefixo (alias legado: `options`)
`channels`	Lista canais NixOS disponíveis
`flake-inputs`	Explora entradas locais de flakes do store do Nix
`cache`	Verifica o status do cache binário para pacotes
`store`	Lê arquivos ou lista diretórios em um caminho `/nix/store` explícito (requer Nix)

Fonte	O que consulta
`nixos`	Pacotes, opções, programas
`home-manager`	Opções do Home Manager
`darwin`	Opções do nix-darwin
`flakes`	Flakes da comunidade (search.nixos.org)
`flakehub`	Registro FlakeHub (flakehub.com)
`nixvim`	Opções de configuração do Neovim via Nixvim
`nvf`	Opções de configuração do Neovim via NVF (docs instáveis mais recentes)
`noogle`	Assinaturas e documentação de funções Nix (noogle.dev)
`wiki`	Artigos da Wiki NixOS (wiki.nixos.org)
`nix-dev`	Documentação oficial do Nix (nix.dev)
`nixhub`	Metadados de pacotes e caminhos de store (nixhub.io)

Os resultados do NVF usam caminhos de opção canônicos vim.*. As consultas também podem usar a forma abreviada programs.nvf.vim.* ou o caminho de módulo NixOS/Home Manager programs.nvf.settings.vim.*; ambos são normalizados automaticamente.

Exemplos:

# 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` — Histórico de Versões de Pacotes

Encontre versões históricas com hashes de commit do nixpkgs. A saída inclui:

Metadados do pacote (licença, homepage, programas) quando disponíveis
Disponibilidade de plataforma por versão (Linux/macOS)
Hash de commit do nixpkgs para builds reproduzíveis
Caminho de atributo para expressões Nix

nix_versions(package, version, limit)

Exemplos:

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

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

Instalação

Você NÃO precisa ter o Nix instalado. Isso roda em qualquer lugar onde o Python roda.

# Run directly (no install)
uvx mcp-nixos

# Or install
pip install mcp-nixos

Para usuários de Nix:

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

Instalação Declarativa (NixOS / Home Manager / nix-darwin)

mcp-nixos está disponível em 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 ];

Ou use o flake diretamente com o overlay fornecido:

# 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 apenas adiciona pkgs.mcp-nixos. O pacote carrega sua própria pilha FastMCP 4 / MCP SDK 2 (veja nix/fastmcp4.nix), incluindo um starlette em ou acima do piso de segurança 1.0.1 que o FastMCP exige, então nada mais no seu conjunto de pacotes Python muda, mesmo em canais nixpkgs que ainda enviam FastMCP 3. Se você também quiser pkgs.python3Packages.fastmcp atualizado em todo o conjunto, aplique mcp-nixos.overlays.fastmcp4 adicionalmente.

Desenvolvimento

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

Agradecimentos

NixHub.io — Histórico de versões de pacotes
search.nixos.org — Busca oficial do NixOS
FlakeHub — Registro de flakes da Determinate Systems
Jetify — Criadores do Devbox e NixHub
Noogle — Mecanismo de busca de funções Nix
NuschtOS — Infraestrutura de busca estática de opções que alimenta o suporte ao Nixvim
Nixvim — Framework de configuração do Neovim para Nix
NVF — Framework de configuração do Neovim e catálogo de opções publicado

Licença

MIT — Porque compartilhar é se importar.

Criado por James Brink. Mantido por entusiastas mass̶o̶c̶h̶i̶s̶t̶a̶s̶ que gostam de Nix.