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 许可证。