Skip to main content
Glama
Sign In
enesjakozh

mcp-nixos

by utensils
Verified
GitHub
Python
MIT License
65
  • Linux
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Integrates with Codecov for tracking code coverage statistics from the project's test suite, with links to coverage reports.

  • Connects to the NixOS Elasticsearch API to query package information and system options with field-specific search boosts, multiple channel support, and error handling.

  • Offers specific integration for Firefox configuration in Home Manager, enabling access to Firefox profiles and settings information through dedicated search and info tools.

MCP-NixOS——因为你的人工智能助手不应该对软件包产生幻觉

⚠️ 积极开发：此软件包正在积极开发中。就像我的职业选择一样，它也在不断发展。

📢 已重命名：此软件包已从nixmcp重命名为mcp-nixos并已在 0.2.0 版本中发布。请相应地更新您的参考资料，或继续沿用旧版本——您可以选择。

这是什么玩意？

MCP-NixOS 是一个模型上下文协议服务器，它可以阻止你的 AI 助手编造关于 NixOS 的内容。因为，让我们面对现实吧——唯一比混淆 NixOS 文档更糟糕的事情，就是 AI 自信地对它产生幻觉。

它提供以下实时访问：

  • NixOS 软件包（是的，确实存在的软件包）
  • 系统选项（您将花费数小时进行配置）
  • 家庭管理器设置（当系统范围的混乱还不够时）
  • nix-darwin macOS 配置（因为 Apple 用户也需要复杂性）

快速入门：针对长期不耐烦的人

听着，我们都知道你只会浏览一下这份 README 文件，然后遇到问题就抱怨。以下是入门的最低要求：

{ "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } }

好了。现在你的 AI 助手可以真正地提供关于 NixOS 的正确信息，而不是再凭空想象出 2019 年的软件包名称了。不用客气。

环境变量（针对控制狂）

多变的描述默认
MCP_NIXOS_LOG_LEVEL你有多想知道你的失败信息
MCP_NIXOS_LOG_FILE在哪里记录上述失败（无处——你的秘密是安全的）
MCP_NIXOS_CACHE_DIR在哪里存放你可能会忘记的东西特定于操作系统的缓存位置*
MCP_NIXOS_CACHE_TTL缓存失效多久会毁了你的一天86400（24小时）
MCP_NIXOS_CLEANUP_ORPHANS是否在启动时终止孤立的 MCP 进程错误的
KEEP_TEST_CACHE保留测试缓存目录以供调试（仅限开发）错误的
ELASTICSEARCH_URLNixOS Elasticsearch API URLhttps://search.nixos.org/backend

*默认缓存位置（您的千兆字节将悄悄消失到其中）：

  • Linux： ~/.cache/mcp_nixos/ （因为~/.cache 不够混乱）
  • macOS： ~/Library/Caches/mcp_nixos/ （埋在你永远不会看到的地方）
  • Windows： %LOCALAPPDATA%\mcp_nixos\Cache\ （在 Windows 目录中丢失）

可能真正起作用的功能

  • NixOS 资源：通过 Elasticsearch API 获取软件包和系统选项
    • 多个渠道：不稳定（适合勇敢者）、稳定（适合无聊者）和特定版本
    • 详细的软件包元数据，告诉你除了如何让它工作之外的一切
  • Home Manager ：通过解析文档的用户配置选项
    • 您将花费周末配置的程序、服务和设置
    • 当你想要获得极其具体的内容时，可以使用分层路径
  • nix-darwin ：针对“顺便说一下，我使用 NixOS”的 Apple 用户的 macOS 配置
    • Apple 从未打算让你触碰的系统默认设置、服务和设置
    • 以全新且令人兴奋的方式破解您的 Mac！
  • 智能缓存：因为没有人愿意等待 Elasticsearch 查询
    • 减少网络请求并缩短启动时间
    • 缓存后即可离线工作（非常适合下次互联网中断时使用）
  • 丰富的搜索：找到您需要的内容或足够接近的内容
    • 快速的内存搜索引擎，出乎意料地还不错
    • 当您不确定要查找什么时的相关选项

MCP 资源和工具：您不知道自己需要的强大工具

NixOS：让你感觉自己既聪明又愚蠢的操作系统

资源：

  • nixos://package/{name} - 查找你确定存在的包
  • nixos://search/packages/{query} - 搜索可能存在的包
  • nixos://search/options/{query} - 搜索系统选项，你可能会配置错误
  • nixos://option/{name} - 获取你仍然会搞砸的选项信息
  • nixos://search/programs/{name} - 查找提供程序的软件包
  • nixos://packages/stats - 给你的书呆子朋友留下深刻印象的统计数据

工具：

  • nixos_search(query, type, channel) - 您最常用的搜索功能
  • nixos_info(name, type, channel) - 获取包或选项详细信息
  • nixos_stats(channel) - 获取没人要求的 NixOS 统计数据

渠道：

  • unstable （默认）——生活在边缘，没有什么是稳定的，包括你的理智
  • stable (24.11) - 适合那些喜欢按计划中断的人
  • 旧版本——当你怀念以前的失败时

家庭经理：因为系统范围的配置不够复杂

资源：

  • home-manager://search/options/{query} - 搜索用户配置选项
  • home-manager://option/{name} - 稍后您将截取选项详细信息
  • home-manager://options/prefix/{prefix} - 前缀下的所有选项
  • home-manager://options/{category} - 类别选项（程序、服务等）

工具：

  • home_manager_search(query) - 搜索配置选项
  • home_manager_info(name) -获取带有实际解释的选项详细信息
  • home_manager_options_by_prefix(option_prefix) - 通过前缀获取选项
  • home_manager_list_options() - 不堪重负时列出所有选项类别

nix-darwin：为渴望痛苦的 Mac 用户

资源：

  • darwin://search/options/{query} - 搜索 macOS 选项
  • darwin://option/{name} - 您的 Apple 设备的选项详情
  • darwin://options/prefix/{prefix} - 前缀下的所有选项
  • darwin://options/{category} - 类别选项（系统、服务等）

工具：

  • darwin_search(query) - 搜索 macOS 配置选项
  • darwin_info(name) - 获取 Apple 不想让你知道的选项详细信息
  • darwin_options_by_prefix(option_prefix) - 通过前缀获取选项
  • darwin_list_options() - 列出所有选项类别

工具使用示例（可复制/粘贴）

# NixOS examples for when you're pretending to know what you're doing nixos_search(query="firefox", type="packages", channel="unstable") nixos_search(query="postgresql", type="options", channel="stable") nixos_info(name="firefox", type="package") nixos_info(name="services.postgresql.enable", type="option") # Home Manager examples for the domestic configuration enthusiasts home_manager_search(query="programs.git") home_manager_info(name="programs.firefox.enable") home_manager_options_by_prefix(option_prefix="programs.git") # nix-darwin examples for the masochistic Mac users darwin_search(query="system.defaults.dock") darwin_info(name="services.yabai.enable") darwin_options_by_prefix(option_prefix="system.defaults")

安装和配置：您可能会跳过的部分

安装它（选择你的毒药）

# Option 1: Install with pip like a normie pip install mcp-nixos # Option 2: Install with uv because you're too cool for pip uv pip install mcp-nixos # Option 3: Run directly with uvx (recommended for the truly enlightened) uvx --install-deps mcp-nixos

配置它（你肯定会搞砸的部分）

添加到您的 MCP 配置文件（例如~/.config/claude/config.json ）：

{ "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } }

对于使用源代码进行开发（对于那些喜欢惩罚的人）：

{ "mcpServers": { "nixos": { "command": "uv", "args": ["run", "-m", "mcp_nixos.__main__"], "env": { "PYTHONPATH": "." } } } }

缓存和通道：魔法发生和文件消失的地方

缓存系统：

  • 5 分钟后你就会忘记的默认位置
  • 存储 HTML 内容、序列化数据和搜索索引
  • 缓存后可离线工作（这是您真正欣赏的唯一功能）

NixOS 频道：

  • unstable ：最新的 NixOS 不稳定版（适合冒险者）
  • stable ：当前稳定版本（适合规避风险的用户）
  • 24.11 ：特定版本参考（适合历史倾向者）

开发：对于那些不满足于仅仅使用物品的人

依赖关系（因为没有任何东西再独立存在）

该项目使用pyproject.toml因为我们不是动物。

# Install development dependencies for the brave pip install -e ".[dev]" # Or with uv (recommended for the enlightened) uv pip install -e ".[dev]"

使用 Nix（当然有 Nix 开发环境）

# Enter dev shell and see available commands nix develop && menu # Common commands for common folk run # Start the server (and your journey into madness) run-tests # Run tests with coverage (expose the flaws) lint # Format and lint code (fix the mess you made) publish # Build and publish to PyPI (share your pain)

测试（是的，我们确实这么做）

测试使用真实的 Elasticsearch API 调用而不是模拟，因为我们不惧怕现实世界：

# Run tests with coverage (default and recommended) run-tests # Run tests without coverage (for those who prefer blissful ignorance) run-tests --no-coverage

代码覆盖率在Codecov上进行跟踪（我们假装关心 100% 的覆盖率）。

与 LLM 结合使用：本练习的重点

配置完成后，在 MCP 兼容型号的提示中使用 MCP-NixOS：

# NixOS resources for the confused ~nixos://package/python ~nixos://option/services.nginx ~nixos://search/packages/firefox # Home Manager resources for the domestically challenged ~home-manager://search/options/programs.git ~home-manager://option/programs.firefox.profiles # nix-darwin resources for the Apple addicted ~darwin://search/options/system.defaults.dock # NixOS tools for the tool-inclined ~nixos_search(query="postgresql", type="options") ~nixos_info(name="firefox", type="package", channel="unstable") # Home Manager tools for home improvement ~home_manager_search(query="programs.zsh") ~home_manager_info(name="programs.git.userName") # nix-darwin tools for the Mac masochists ~darwin_search(query="services.yabai") ~darwin_info(name="system.defaults.dock.autohide")

LLM 将通过 MCP 服务器获取信息，并且可能实际上会给你一次正确的信息。

实施细节：揭秘《纸牌屋》

代码架构：我们如何实现它（某种方式）

MCP-NixOS 采用模块化结构，尽管面临种种困难，但仍能正常工作：

  • mcp_nixos/cache/ - 缓存组件，节省带宽和理智
  • mcp_nixos/clients/ - 与 Elasticsearch 通信并解析 HTML 文档的 API 客户端
  • mcp_nixos/contexts/ - 上下文对象，防止一切崩溃
  • mcp_nixos/resources/ - 所有平台的 MCP 资源定义
  • mcp_nixos/tools/ - 执行实际工作的 MCP 工具实现
  • mcp_nixos/utils/ - 实用功能，因为我们不是动物
  • mcp_nixos/server.py将这座纸牌屋粘合在一起的胶水

NixOS API 集成：外部连接

使用以下方式连接到 NixOS Elasticsearch API：

  • 多渠道支持（不稳定、稳定/24.11）
  • 特定字段搜索增强，提高相关性
  • 错误处理，预期最坏的结果，但希望最好的结果（我的人生故事）

HTML 文档解析器：梦想消亡的地方

对于 Home Manager 和 nix-darwin 选项，我们对 HTML 解析犯下了罪行：

  1. 文档解析器：通过 BeautifulSoup 咒语、正则表达式黑魔法以及连续 72 小时盯着畸形 HTML 的决心来提取结构化数据。
  2. 搜索引擎：拼凑而成：
    • 用于快速文本搜索的倒排索引（当它不会翻倒时）
    • 用于分层查找的前缀树（凌晨 3 点时似乎是个好主意）
    • 根据一种被称为“基于共鸣的排序”的算法对结果进行评分
  3. 缓存系统：因为解析 HTML 一次就已经够麻烦了：
    • 存储 HTML 内容、处理后的数据结构和搜索索引
    • 使用特定于平台的缓存位置，因此您不必考虑它
    • 实现基于 TTL 的过期功能，以便在需要时刷新内容
    • 当事情不可避免地出错时，能够优雅地退缩（与我的人际关系不同）

什么是模型上下文协议？

对于那些直接跳到结尾的人

模型上下文协议 (MCP)是一种开放协议，它使用 JSON 消息通过标准输入/输出 (stdin/stdout) 将 LLM 连接到外部数据和工具。本项目实现了 MCP，使 AI 助手能够访问 NixOS、Home Manager 和 nix-darwin 资源，这样它们就终于可以不再对你的操作系统进行胡编乱造了。

执照

麻省理工学院（因为我不是怪物）

NixOS 雪花徽标的使用已注明出处。详情请参阅出处信息。

由自称“恐怖修补匠”的詹姆斯·布林克 (James Brink) 创作，他不知何故设法让事情顺利进行。

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

View all tools

MCP-NixOS 是一个模型上下文协议服务器，它提供有关 NixOS 包、选项、Home Manager 和 nix-darwin 配置的实时、准确信息，防止 AI 助手对 NixOS 资源产生幻觉，并使其能够提供真实的系统配置指导。

  1. What The Hell Is This Thing?
    1. Quick Start: For the Chronically Impatient
      1. Environment Variables (For Control Freaks)
    2. Features That Might Actually Work
      1. MCP Resources & Tools: The Power Tools You Didn't Know You Needed
        1. NixOS: The OS That Makes You Feel Simultaneously Smarter and Dumber
        2. Home Manager: Because System-Wide Configuration Wasn't Complicated Enough
        3. nix-darwin: For Mac Users Who Crave Pain
        4. Tool Usage Examples (Copy/Paste Ready)
      2. Installation & Configuration: The Part You'll Probably Skip
        1. Install It (Pick Your Poison)
        2. Configure It (The Part You'll Definitely Mess Up)
        3. Cache & Channels: Where Magic Happens and Files Disappear
      3. Development: For Those Not Content With Just Using Things
        1. Dependencies (Because Nothing Stands Alone Anymore)
        2. Using Nix (Of Course There's a Nix Development Environment)
        3. Testing (Yes, We Actually Do That)
      4. Using with LLMs: The Whole Point of This Exercise
        1. Implementation Details: The House of Cards Revealed
          1. Code Architecture: How We Made This Work (Somehow)
          2. NixOS API Integration: The External Connection
          3. HTML Documentation Parsers: Where Dreams Go To Die
        2. What is Model Context Protocol?
          1. For Those Who Skipped Straight to the End
        3. License

          Related Resources

          Appeared in Searches

          ID: j13wrfj9az