MCP-NixOS - Because Your AI Assistant Shouldn't Hallucinate About Packages

MCP-NixOS——因为你的 AI 不该臆造软件包名称

快速开始

🚨 无需 Nix/NixOS！ 可在任何系统上运行——Windows、macOS、Linux。你只是在查询 API。

选项 1：uvx（推荐）

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

选项 2：Nix

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

选项 3：Docker

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

现在，你的 AI 可以访问真实的 NixOS 数据，而不是凭空捏造。举手之劳，不必客气。

选项 4：HTTP（远程 MCP）

FastMCP 支持通过 URL 使用 HTTP 运行此服务（MCP 端点默认为 /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（默认）：

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

自定义路径：

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

无状态 HTTP（禁用客户端会话状态）：

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

选项 5：Pi 编码 Agent

Pi 原生不支持 MCP。支持以下两种方式：

A. pi-mcp-adapter（推荐——支持 MCP，单一事实来源）：

pi install npm:pi-mcp-adapter

然后添加到 ~/.pi/agent/mcp.json：

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

B. 项目本地扩展（克隆并运行）： 此仓库提供 .pi/extensions/mcp-nixos.ts，在克隆的仓库中运行 pi 时会自动加载。可选：运行 cd .pi && npm install，以解析编辑器类型。无论如何，Pi 都会运行它。

这是什么？

一个 MCP 服务，可提供准确、实时的信息，包括：

• NixOS 软件包——实际存在的 13 万多个软件包
• NixOS 选项——23,000 多种系统配置方式
• Home Manager——供 dotfile 爱好者使用的 5,000 多个选项
• nix-darwin——1,000 多项 Apple 未公开的 macOS 设置
• Nixvim——通过 NuschtOS search 配置 Neovim 的 5,000 多个选项
• NVF——来自其已发布的不稳定版文档的 2,400 多个 Neovim 选项
• FlakeHub——来自 FlakeHub.com 注册表的 600 多个 flake
• Noogle——通过 noogle.dev 提供的 2,000 多个带类型签名的 Nix 函数
• NixOS Wiki——来自 wiki.nixos.org 的社区文档和指南
• nix.dev——来自 nix.dev 的官方 Nix 教程和指南
• 软件包版本——通过 NixHub.io 提供带提交哈希的历史版本
• 二进制缓存状态——检查软件包是否缓存在 cache.nixos.org，并查看下载大小
• 本地 flake 输入——直接从 Nix store 探索固定的 flake 依赖项（需要 Nix）

工具

只有两个。我们将 17 个工具整合成 2 个，因为 AI 的上下文窗口并非无限。

总计约 1,030 个令牌。 就这些。其他 MCP 服务像黑色星期五抢购一样占用你的上下文，而我们则在角落里悠闲地品着极简主义的茶。你的 AI 无需臃肿负担，就能获得 NixOS 超能力。

nix - 统一查询工具

一个工具，统领一切：

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

version 和 system 仅用于 action="cache"。

操作	功能
search	搜索软件包、选项、程序或 flake
info	获取软件包或选项的详细信息
stats	获取数量和类别
browse	按前缀浏览 Home Manager、Darwin、Nixvim、NVF 或 Noogle（旧别名：options）
channels	列出可用的 NixOS channel
flake-inputs	从 Nix store 探索本地 flake 输入
cache	检查软件包的二进制缓存状态
store	读取文件或列出显式 /nix/store 路径下的目录（需要 Nix）

来源	查询内容
nixos	软件包、选项、程序
home-manager	Home Manager 选项
darwin	nix-darwin 选项
flakes	社区 flake（search.nixos.org）
flakehub	FlakeHub 注册表（flakehub.com）
nixvim	Nixvim Neovim 配置选项
nvf	NVF Neovim 配置选项（最新不稳定版文档）
noogle	Nix 函数签名和文档（noogle.dev）
wiki	NixOS Wiki 文章（wiki.nixos.org）
nix-dev	Nix 官方文档（nix.dev）
nixhub	软件包元数据和 store 路径（nixhub.io）

NVF 结果使用规范的 vim.* 选项路径。查询也可以使用简写 programs.nvf.vim.*，或 NixOS/Home Manager 模块路径 programs.nvf.settings.vim.*；两者都会自动规范化。

示例：

# 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 - 软件包版本历史

查找带有 nixpkgs 提交哈希的历史版本。输出包括：

• 软件包元数据（许可证、主页、程序；如果有）
• 各版本的平台可用情况（Linux/macOS）
• 用于可复现构建的 Nixpkgs 提交哈希
• Nix 表达式的属性路径

nix_versions(package, version, limit)

示例：

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

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

安装

无需安装 Nix。 只要能运行 Python，在哪里都能运行。

# Run directly (no install)
uvx mcp-nixos

# Or install
pip install mcp-nixos

Nix 用户请看：

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

声明式安装（NixOS / Home Manager / nix-darwin）

mcp-nixos 已在 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 ];

或者使用提供了 overlay 的 flake：

# 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 只会添加 pkgs.mcp-nixos。该软件包携带自己的 FastMCP 4 / MCP SDK 2 技术栈（参见 nix/fastmcp4.nix），其中包含 FastMCP 所需的版本不低于 1.0.1 的 starlette 安全版本。因此，即使使用仍提供 FastMCP 3 的 nixpkgs channel，Python 软件包集合中的其他内容也不会发生变化。 如果还希望将 pkgs.python3Packages.fastmcp 本身升级到整个集合中，请额外应用 mcp-nixos.overlays.fastmcp4。

开发

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

致谢

• NixHub.io - 软件包版本历史
• search.nixos.org - NixOS 官方搜索
• FlakeHub - Determinate Systems 提供的 Flake 注册表
• Jetify - Devbox 和 NixHub 的创建者
• Noogle - Nix 函数搜索引擎
• NuschtOS - 为 Nixvim 支持提供支持的静态选项搜索基础设施
• Nixvim - 面向 Nix 的 Neovim 配置框架
• NVF - Neovim 配置框架及已发布的选项目录

许可证

MIT - 分享就是关爱。

---

由 James Brink 创建。由热爱 Nix 的狂̶热̶爱̶好̶者̶爱好者维护。