Nixos MCP

🚀 NixOS MCP Server

NixOSの設定オプションをClaude Codeから直接検索できる、Model Context Protocol (MCP) サーバーです。

✨ 主な機能

• キーワードまたはフレーズでNixOSの設定オプションを検索できます。
• オプション名、型、デフォルト値、および説明を返します。
• 大量の検索結果に対応したページネーション機能があります。
• TypeScriptで構築され、Node 24以上と互換性があります。
• 効率的な検索：公式のNixOS検索APIエンドポイントを使用しています。
• NixOS 25.11：最新のNixOSチャンネル (25.11) を対象に検索します。
• 型安全：完全なTypeScript型定義があります。
• 入力検証：すべての入力に対してZodスキーマ検証を行います。
• エラーハンドリング：無効なクエリやAPIの問題に対して適切なエラーメッセージを表示します。
• ページネーションサポート：大量の検索結果を効率的に処理できます。

📦 インストール

1. リポジトリをクローンします：

cd /path/to/nixos-mcp
npm install

📚 ドキュメント

Claude Codeの設定

このMCPサーバーをClaude Codeと一緒に使用するには、Claude Codeの設定ファイルで設定する必要があります。

Linux/macOS

~/.config/claude/claude_code_config.json を編集します：

{
  "mcpServers": {
    "nixos-search": {
      "command": "node",
      "args": [
        "/absolute/path/to/nixos-mcp/src/index.ts"
      ]
    }
  }
}

Windows

%APPDATA%\claude\claude_code_config.json を編集します：

{
  "mcpServers": {
    "nixos-search": {
      "command": "node",
      "args": [
        "C:\\absolute\\path\\to\\nixos-mcp\\src\\index.ts"
      ]
    }
  }
}

Claude Codeの再起動

設定を追加した後、MCPサーバーをロードするためにClaude Codeを再起動します。

使用方法

設定が完了すると、Claude Codeから直接NixOSのオプションを検索できます。以下はいくつかの検索クエリの例です：

• "Search for nginx options in NixOS"（NixOSでnginxのオプションを検索）
• "Find networking firewall configuration options"（ネットワークファイアウォールの設定オプションを検索）
• "What NixOS options are available for SSH?"（SSHに利用可能なNixOSのオプションは何か？）
• "Search for services.postgresql options"（services.postgresqlのオプションを検索）

利用可能なツール

search_nixos_options

NixOSの設定オプションを検索します。

パラメーター:

• query (文字列、必須): NixOSオプションの検索クエリ
  • 例: "nginx", "networking firewall", "services.postgresql"
• from (数値、オプション): ページネーションの開始インデックス
  • デフォルト: 0
  • これを使用して、検索結果の次のページを取得します。
• size (数値、オプション): 1ページあたりの検索結果数
  • デフォルト: 20
  • 範囲: 1 - 50

例:

search_nixos_options {
  query: "nginx services",
  size: 10
}

レスポンス形式:

"query"に対するX件の検索結果が見つかりました:

1. option.name.here
   型: string
   デフォルト: "default value"
   説明: オプションの説明...

2. another.option.name
   型: boolean
   デフォルト: false
   説明: 別のオプションの説明...

---
全X件中の1 - 10件を表示しています

開発

ローカルでサーバーを実行する

Claude Codeを設定せずにサーバーをテストするには：

npm start

コード品質

コードを整形する：

npm run format

型チェックを行う：

npm run typecheck

アーキテクチャ

src/
├── index.ts              # MCPサーバーのエントリーポイント
├── types.ts              # TypeScript型定義
├── nixos-client.ts       # NixOS APIクライアント
└── tools/
    └── search-options.ts # 検索ツールの実装

トラブルシューティング

サーバーが起動しない場合

• Node 24以上がインストールされていることを確認します: node --version
• 設定ファイル内の src/index.ts のパスが正しいことを確認します。
• Claude CodeのMCPサーバーログにエラーメッセージがないか確認します。

検索結果が見つからない場合

• より具体的な検索用語を試してみます。
• 一般的なNixOSオプション名や接頭辞（例: "services.nginx", "networking"）を使用します。
• NixOS検索ポータル を参照してください。

接続問題が発生した場合

• 設定ファイルの構文が有効なJSONであることを確認します。
• 絶対パスが正しいことを確認します。
• 設定を更新した後、Claude Codeを再起動します。

APIの詳細

このサーバーは公式のNixOS検索APIを使用しています：

• エンドポイント: https://search.nixos.org/backend/latest-44-nixos-25.11/_search
• チャンネル: NixOS 25.11
• タイプ: 設定オプションのみを検索します（パッケージは検索しません）

📄 ライセンス

ISC