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 コーディングエージェント

Pi は MCP にネイティブ対応していません。サポートされている方法は 2 つあります。

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 パッケージ - 実際に存在する 130K 以上のパッケージ
• NixOS オプション - システムを設定する 23K 以上の方法
• Home Manager - dotfile 愛好家向けの 5K 以上のオプション
• nix-darwin - Apple が文書化していない 1K 以上の macOS 設定
• Nixvim - NuschtOS search 経由で Neovim を設定する 5K 以上のオプション
• NVF - 公開されている unstable ドキュメントから取得した 2.4K 以上の Neovim オプション
• FlakeHub - FlakeHub.com レジストリにある 600 以上の flake
• Noogle - noogle.dev 経由で、型シグネチャ付きの 2K 以上の Nix 関数
• NixOS Wiki - wiki.nixos.org のコミュニティドキュメントとガイド
• nix.dev - nix.dev の公式 Nix チュートリアルとガイド
• パッケージのバージョン - NixHub.io 経由で、コミットハッシュ付きの過去のバージョン
• バイナリキャッシュの状態 - パッケージが cache.nixos.org にキャッシュされているかどうかを、ダウンロードサイズとともに確認
• ローカルの flake 入力 - Nix ストアからピン留めされた flake の依存関係を直接確認（Nix が必要です）

ツール

ツールは 2 つだけです。AI のコンテキストウィンドウは無限ではないため、17 個のツールを 2 個に統合しました。

合計約 1,030 トークンです。 それだけです。他の MCP サーバーがブラックフライデーのようにコンテキストを占領している間、私たちは片隅でミニマリストなお茶を楽しんでいます。余計なものを増やさずに、AI に NixOS のスーパーパワーを与えます。

nix - 統合クエリツール

すべてを統べる 1 つのツールです。

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 チャネルを一覧表示します
flake-inputs	Nix ストアからローカルの 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 設定オプション（最新の unstable ドキュメント）
noogle	Nix 関数のシグネチャとドキュメント（noogle.dev）
wiki	NixOS Wiki の記事（wiki.nixos.org）
nix-dev	Nix の公式ドキュメント（nix.dev）
nixhub	パッケージのメタデータとストアパス（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 ];

または、提供されているオーバーレイを使ってフレークを直接利用できます。

# 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 も含まれています。そのため、Python パッケージセット内の ほかのパッケージには変更がありません。FastMCP 3 を提供している nixpkgs チャネルでも同様です。 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 によるフレークレジストリ
• Jetify - Devbox と NixHub の開発元
• Noogle - Nix 関数検索エンジン
• NuschtOS - Nixvim サポートを支える静的オプション検索インフラストラクチャ
• Nixvim - Nix 用 Neovim 設定フレームワーク
• NVF - Neovim 設定フレームワークと公開オプションカタログ

ライセンス

MIT - 共有は思いやりです。

---

James Brink が作成。Nix を楽しむ̶マ̶ゾ̶ヒ̶ス̶ト̶愛好家がメンテナンスしています。