Nixos MCP

🚀 NixOS MCP 服務器

NixOS MCP 服務器是一個基於模型上下文協議（MCP）的工具，它允許你直接從 Claude Code 中搜索 NixOS 配置選項，為開發者提供了便捷的配置搜索體驗。

🚀 快速開始

要使用 NixOS MCP 服務器，你需要完成安裝和配置步驟。安裝完成並配置好後，即可直接在 Claude Code 中搜索 NixOS 配置選項。

✨ 主要特性

• 關鍵詞搜索：支持通過關鍵詞或短語搜索 NixOS 配置選項。
• 詳細信息返回：返回選項名稱、類型、默認值和描述。
• 分頁支持：對於大量搜索結果，提供分頁功能。
• 技術棧優勢：使用 TypeScript 構建，兼容 Node 24+。
• 高效搜索：使用官方 NixOS 搜索 API 端點。
• 緊跟版本：針對最新的 NixOS 通道（25.11）進行搜索。
• 類型安全：具備完整的 TypeScript 類型定義。
• 輸入驗證：使用 Zod 模式驗證所有輸入。
• 錯誤處理：針對無效查詢或 API 問題提供優雅的錯誤消息。

📦 安裝指南

環境要求

• Node.js 24 或更高版本（以支持原生 TypeScript）
• npm 或 yarn

安裝步驟

1. 克隆倉庫並安裝依賴：

cd /path/to/nixos-mcp
npm install

📚 詳細文檔

為 Claude Code 進行配置

要在 Claude Code 中使用此 MCP 服務器，需要在 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

添加配置後，重啟 Claude Code 以使 MCP 服務器加載生效。

使用方法

配置完成後，你可以直接在 Claude Code 中搜索 NixOS 選項。以下是一些示例查詢：

• "Search for nginx options in NixOS"（搜索 NixOS 中的 nginx 選項）
• "Find networking firewall configuration options"（查找網絡防火牆配置選項）
• "What NixOS options are available for SSH?"（NixOS 中有哪些 SSH 選項？）
• "Search for services.postgresql options"（搜索 services.postgresql 選項）

可用工具

search_nixos_options

用於搜索 NixOS 配置選項。

參數說明：

• query（字符串，必需）：NixOS 選項的搜索查詢。
  • 示例："nginx"、"networking firewall"、"services.postgresql"
• from（數字，可選）：分頁的起始索引。
  • 默認值：0
  • 用於獲取後續頁面的結果
• size（數字，可選）：每頁的結果數量。
  • 默認值：20
  • 範圍：1 - 50

使用示例：

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

響應格式：

Found X results for "query":

1. option.name.here
   Type: string
   Default: "default value"
   Description: Description of the option...

2. another.option.name
   Type: boolean
   Default: false
   Description: Another option description...

---
Showing results 1-10 of X total

開發相關

本地運行服務器

若要在不配置 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 許可證。