JinDaGe - nixos-mcp MCP Details

article

README

🚀 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

安装步骤

克隆仓库并安装依赖：

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

nixos-mcp