MCP-NixOS v2.4.3 improves LLM discoverability of the server with a server-level instructions string, an INTENTS → CALLS recipe block in the nix tool, deterministic action=info matching that no longer silently substitutes packages with shared pnames, and per-channel nixpkgs HEAD revisions in action=channels.

Closes #146. Drop-in replacement for v2.4.2 — no configuration or API changes.

Highlights

• Server-level instructions surfaced via the MCP InitializeResult so hosts prime the model on when to reach for this server vs. Bash / web search.
• action=info now matches by exact attribute path first, then exact pname, with explicit JSON-shaped disambiguation hints when multiple attrs share a pname (firefox / firefox-esr / firefox-mobile).
• action=channels now surfaces a Revision (indexed) for unstable channels (exact build commit) and a Branch HEAD (best-effort, 10-min TTL) for release channels — clearly distinguished so callers know which one to compare against nix_versions.
• 12 new unit tests; 348 total (was 336).

See RELEASE_NOTES.md for the full breakdown.

Install

pip install mcp-nixos==2.4.3
nix run github:utensils/mcp-nixos
docker pull ghcr.io/utensils/mcp-nixos:2.4.3

Overview

MCP-NixOS v2.4.2 fixes a startup crash when the server is launched from a working directory containing a non-UTF-8 .env file (e.g. git-crypt ciphertext, sops-encrypted dotenv, or any binary blob).

Previously, fastmcp's top-level Settings() construction ran python-dotenv on .env in the process CWD at import time, and a non-UTF-8 byte anywhere in that file took the whole server down with a UnicodeDecodeError — before the MCP stdio handshake ever ran. Clients (Claude Code, opencode, Roo, Pi, etc.) just saw mcp-nixos fail to initialise.

Changes

🔧 Bug Fixes

• Survive non-UTF-8 .env in CWD (#144, #145): mcp_nixos/__init__.py now defaults FASTMCP_ENV_FILE to os.devnull via os.environ.setdefault, before any submodule imports fastmcp. mcp-nixos does not read any values from fastmcp's .env lookup, so pointing fastmcp at a known-empty path sidesteps the crash without behavior loss. Users who legitimately need a fastmcp dotenv can still set FASTMCP_ENV_FILE explicitly and it will be respected.

🧪 Tests

• Added tests/test_env_file_safety.py — three subprocess-based regression tests that exercise the non-UTF-8 .env, explicit-override, and default-value paths.

📚 Documentation

• Website migrated from Next.js + Tailwind to VitePress 1.6 with a small custom theme (#143). No behavioral change to the Python package.

Installation

pip install mcp-nixos==2.4.2
# or
uvx mcp-nixos
# or
nix run github:utensils/mcp-nixos

Docker

docker pull ghcr.io/utensils/mcp-nixos:2.4.2
docker pull utensils/mcp-nixos:2.4.2

Migration Notes

Drop-in replacement for v2.4.1. No configuration or API changes. If you previously worked around this bug with FASTMCP_ENV_FILE=/dev/null or a CWD-change wrapper, you can remove those shims.

Contributors

• @jamesbrink — fix, tests
• Reporter: @versality (#144) — excellent reproducer and suggested fix path

Full changelog: https://github.com/utensils/mcp-nixos/compare/v2.4.1...v2.4.2

Overview

Patch release fixing the fastmcp3 Nix flake overlay for downstream consumers whose nixpkgs does not contain griffelib or uncalled-for. Both packages were added to nixos-unstable on 2026-03-18 and are absent from stable (nixos-25.11) and older unstable pins. No runtime, API, or Python-package changes — this release only affects Nix flake consumers.

Bug Fixes

• Flake overlay compatibility (#135, #136): overlays.fastmcp3 previously referenced pyFinal.griffelib and pyFinal.uncalled-for directly, which failed with error: attribute 'griffelib' missing for any consumer using inputs.nixpkgs.follows = "nixpkgs" against a nixpkgs that predates those packages. The overlay now guards both references with or fallbacks that callPackage local derivations (nix/griffelib.nix, nix/uncalled-for.nix) when the consumer's nixpkgs lacks them. Consumers on current unstable continue to use upstream packages unchanged — the fallback only triggers when the attribute is missing.

Installation

pip install mcp-nixos==2.4.1
# or
uv pip install mcp-nixos==2.4.1
# or
nix run github:utensils/mcp-nixos

Migration

Drop-in replacement for v2.4.0. If you're a Nix flake consumer who pinned v2.4.0 with inputs.nixpkgs.follows against a stable or older nixpkgs, bump to v2.4.1 to unblock the build.

Reporter: @rolfst (#135)

MCP-NixOS: v2.4.0 Release Notes - FastMCP 3.x Upgrade

Overview

MCP-NixOS v2.4.0 upgrades the framework dependency to FastMCP 3.x (fastmcp>=3.2.0). No user-facing behavior changes — this is a dependency bump needed to keep the project buildable alongside downstream nixpkgs work that moves consumers (e.g. ha-mcp) onto FastMCP 3 (tracked in NixOS/nixpkgs#511658).

Changes in v2.4.0

🚀 Framework

• FastMCP 3.x upgrade (#127, #130): Bumped fastmcp>=2.11.0 → fastmcp>=3.2.0 in pyproject.toml. The server's API surface (constructor, @mcp.tool(), mcp.run() with stdio/http kwargs) is unchanged; both transports continue to work identically.
• Nix flake fastmcp 3 override: The flake overlay temporarily overrides python3Packages.fastmcp to build PrefectHQ/fastmcp v3.2.4 directly, mirroring pending nixpkgs PR #510339. The override lives in overlays.fastmcp3 and is composed into overlays.default, so downstream consumers applying mcp-nixos.overlays.default get the upgraded fastmcp automatically. Removable once upstream nixpkgs catches up.
• aarch64-linux docker build (#131): Dropped pydocket from the inherited runtime deps in the fastmcp override — matches the upstream PR which moves it to optional-dependencies.tasks. Without this, pydocket pulled in lupa, whose bundled libluajit.a fails to link on aarch64-linux. Multi-arch Docker images now build cleanly on both amd64 and arm64 again.
• Test shim for fastmcp 2.x / 3.x compat: tests/test_tools.py, tests/test_integration.py, and tests/test_flake_inputs.py now use getattr(tool, "fn", tool) instead of tool.fn. FastMCP 2.x and the PyPI wheel of 3.2.4 wrap @mcp.tool() as FunctionTool (has .fn), while the nix-built 3.2.4 returns a plain async function. Same shim the .pi wrapper already uses.

⚠️ Breaking (for package consumers)

• If you had fastmcp==2.x pinned elsewhere in your environment alongside mcp-nixos, pip/uv will now refuse to resolve. Upgrade fastmcp to >=3.2.0 or remove the pin.

🧹 Docs

• CLAUDE.md updated to say "FastMCP 3.x server" and cite the actual pin (fastmcp>=3.2.0).

🪲 Known non-issues

• The overlay keeps py-key-value-aio at nixpkgs' 0.3.0, which fastmcp 3.2.4 formally wants at >=0.4.4 with the filetree extra. This only affects the fastmcp.server.auth.oauth_proxy import path (missing aiofile) — not used by mcp-nixos. Tracked in #129; resolves naturally when nixpkgs PR #510339 lands.

Installation

# Install with pip
pip install mcp-nixos==2.4.0

# Install with uv
uv pip install mcp-nixos==2.4.0

# Run directly with nix
nix run github:utensils/mcp-nixos

Docker Images

# Pull from Docker Hub
docker pull utensils/mcp-nixos:2.4.0

# Pull from GitHub Container Registry
docker pull ghcr.io/utensils/mcp-nixos:2.4.0

Migration Notes

No runtime or configuration changes. The only practical impact is the transitive dependency upgrade — if anything else in your environment holds fastmcp to 2.x, relax that pin.

Contributors

• James Brink (@utensils) — FastMCP 3 upgrade, flake overlay, release
• Reporter: @JamieMagee (#127) — flagged the downstream nixpkgs upgrade blocker

Overview

MCP-NixOS v2.3.2 improves the nix tool's descriptions and error messages so smaller local models (qwen3.6, qwen3-coder via Pi, etc.) can reliably map intent to the right action/type combo. Also ships a project-local Pi Coding Agent extension.

Addresses #123 and #125.

Highlights

• 🔧 Rename action=options → action=browse (#125) — the old name collided with "the options action" in models' minds; old name kept as silent alias for back-compat.
• 🎯 browse with source=nixos now redirects with the exact correct JSON, so a retry uses the right shape instead of hitting a dead-end error.
• 📚 9 concrete JSON examples in the nix tool docstring — small models rely heavily on example-driven descriptions.
• 🧹 Plain-prose descriptions replace |-separated lists that small models echoed back as pseudo-JSON.
• 🧩 Pi Coding Agent integration — ships a project-local .pi/extensions/mcp-nixos.ts + README "Option 5: Pi Coding Agent" (pi-mcp-adapter path + project-local wrapper path).
• 🛠️ Pi wrapper fixes — fastmcp 2.x compatibility (previously failed with TypeError: 'FunctionTool' object is not callable in Nix dev-shell); cancellation now short-circuits Python-candidate retries.

Verified on ollama/qwen3.6:latest via Pi: the target failure modes from #125 are gone on first-attempt tool calls.

Installation

pip install mcp-nixos==2.3.2

See RELEASE_NOTES.md for the full changelog.

Overview

Fixes package search and info lookups for dotted/namespaced attribute paths (e.g., kdePackages.qt6ct, python314Packages.matplotlib).

Highlights

• Search now queries package_attr_name and extracts pname from dotted names (#118)
• Info lookup falls back to attribute path when pname lookup fails
• Results display full attribute paths so users can identify package sets
• Fixed circular symlinks between CLAUDE.md and AGENTS.md

Installation

pip install mcp-nixos==2.3.1

See RELEASE_NOTES.md for details.

Overview

MCP-NixOS v2.3.0 adds HTTP transport support for Remote MCP, binary cache status checking, NixHub as a rich metadata source, and restructures the codebase into a modular architecture.

Highlights

• HTTP Transport (#104): MCP_NIXOS_TRANSPORT=http with configurable host/port/path and stateless mode — by @ReStranger
• Binary Cache Status (#92): nix(action="cache") checks if packages have pre-built binaries on cache.nixos.org
• NixHub Metadata (#92): nix(source="nixhub") provides license, homepage, store paths, and programs
• Modular Architecture (#94): Codebase split into focused modules under mcp_nixos/sources/
• serverInfo Fix (#109): Package version now correctly reported in MCP serverInfo

Installation

pip install mcp-nixos==2.3.0
uv pip install mcp-nixos==2.3.0
nix run github:utensils/mcp-nixos

Docker

docker pull utensils/mcp-nixos:2.3.0
docker pull ghcr.io/utensils/mcp-nixos:2.3.0

Contributors

• @utensils — Binary cache, NixHub, modular architecture, serverInfo fix
• @ReStranger — HTTP transport support (#104)
• @DavidDudson — pytest config fix (#105)

See RELEASE_NOTES.md for full details.

Overview

MCP-NixOS v2.2.0 adds three new documentation sources and a new flake-inputs action for exploring local Nix store dependencies.

Highlights

• 🔍 NixOS Wiki (source="wiki") - Search and retrieve wiki articles
• 📚 nix.dev (source="nix-dev") - Search official Nix tutorials and guides
• 🔧 Noogle (source="noogle") - Search 2,000+ Nix built-in functions with type signatures
• 📦 Flake Inputs (action="flake-inputs") - Explore local Nix store dependencies (requires Nix)

Installation

pip install mcp-nixos==2.2.0

nix run github:utensils/mcp-nixos

docker pull utensils/mcp-nixos:2.2.0

See RELEASE_NOTES.md for full details.

Overview

MCP-NixOS v2.1.1 fixes the Nix flake by using stable Python in nixpkgs and includes several build system improvements.

Changes in v2.1.1

🔧 Improvements & Bug Fixes

• Stable Python Compatibility: Reverted from Python 3.14 to stable Python 3 in nixpkgs
• Version Retrieval Fix: Dynamic version detection now reads from pyproject.toml when package isn't installed
• Flake Enhancements: Better source filtering, unit tests run during build, versioned Docker tags
• Config Consolidation: Moved pytest config from pytest.ini to pyproject.toml

Contributors

Thanks to Malix - Alix Brunet (@Malix-Labs) for all the cleanup work in this release! 🎉

Installation

pip install mcp-nixos==2.1.1

Or via Nix:

nix run github:utensils/mcp-nixos

See RELEASE_NOTES.md for full details.

Overview

MCP-NixOS v2.1.0 converts to a pure Nix flake build system and adds FlakeHub integration. This release fixes build compatibility with nixpkgs-unstable (issue #67).

Highlights

• 🚀 Pure Nix Flake: Complete rewrite from hybrid venv/pip to pure Nix
• 🌐 FlakeHub Integration: Now available on FlakeHub for easier installation
• 🔧 Build Fix: Resolved fastmcp/mcp version constraint issue with nixpkgs-unstable
• 🐍 Python 3.14: Now builds with Python 3.14 from nixpkgs
• 📦 Proper Overlay: Exposes overlays.default for NixOS/Home Manager integration

Installation

# pip
pip install mcp-nixos==2.1.0

# nix run
nix run github:utensils/mcp-nixos

# FlakeHub
inputs.mcp-nixos.url = "https://flakehub.com/f/utensils/mcp-nixos/*.tar.gz";

See RELEASE_NOTES.md for full details.

Overview

MCP-NixOS v2.0.0 is a major release that consolidates 17 MCP tools into just 2 unified tools, reducing token overhead by 95%. This release also adds comprehensive Nixvim support with 16,600+ configuration options.

Highlights

🎯 95% Token Reduction

• Before: 17 individual tools consuming ~15,000 tokens
• After: 2 unified tools consuming ~1,400 tokens
  • nix (769 tokens) - Unified query tool
  • nix_versions (643 tokens) - Package version history

🚀 Nixvim Support

• 16,647 options from NuschtOS search infrastructure
• Covers plugins (14,216), LSP (1,439), colorschemes (679), and more

⚠️ Breaking Changes

All 17 legacy tools have been removed. See migration guide below.

Migration Guide

| Old Tool | New Equivalent |
|----------|----------------|
| nixos_search | nix action=search source=nixos |
| nixos_info | nix action=info source=nixos |
| home_manager_search | nix action=search source=home-manager |
| darwin_search | nix action=search source=darwin |
| flakes_search | nix action=search source=flakes |
| nixos_channels | nix action=channels |

Installation

pip install mcp-nixos==2.0.0

Docker

docker pull utensils/mcp-nixos:2.0.0
docker pull ghcr.io/utensils/mcp-nixos:2.0.0

See RELEASE_NOTES.md for full details.

Closes #59, #61

Overview

MCP-NixOS v1.1.0 updates to NixOS 25.11 as the new stable channel, fixes the flakes search index, and improves CI/CD reliability.

Highlights

• 🚀 NixOS 25.11 Stable: Updated stable channel to the latest release
• 🔧 Flakes Search Fixed: Resolved Elasticsearch index issues (#62)
• 🛡️ CI Reliability: Added automatic retry for flaky integration tests (#63, #64)
• 📦 Portability: Improved .mcp.json with relative paths

Installation

pip install mcp-nixos==1.1.0

docker pull utensils/mcp-nixos:1.1.0

See RELEASE_NOTES.md for full details.

Overview

MCP-NixOS v1.0.3 fixes encoding errors when parsing Home Manager and nix-darwin documentation, ensuring robust operation with various HTML encodings from CDN edge servers.

Highlights

• 🔧 Fixed HTML Encoding Errors: Resolves intermittent "unknown encoding: windows-1252" errors
• 🌐 Enhanced CDN Resilience: Better handling of documentation served from different edge servers
• ✅ Comprehensive Testing: Added encoding tests for windows-1252, ISO-8859-1, and UTF-8 with BOM

What Changed

The MCP server now uses resp.content instead of resp.text when parsing HTML documentation, allowing BeautifulSoup to automatically detect and handle various encodings. This prevents failures when CDN edge servers serve content with different encoding declarations.

Installation

# Install with pip
pip install mcp-nixos==1.0.3

# Install with uv
uv pip install mcp-nixos==1.0.3

# Install with uvx
uvx mcp-nixos==1.0.3

Docker Images

# Docker Hub
docker pull utensils/mcp-nixos:1.0.3

# GitHub Container Registry
docker pull ghcr.io/utensils/mcp-nixos:1.0.3

See RELEASE_NOTES.md for complete details.

Overview

MCP-NixOS v1.0.2 is a maintenance release focused on CI/CD improvements, security fixes, and enhanced Docker support.

Highlights

• 🚀 Manual workflow dispatch for Docker builds
• 🔒 Automated GHCR package visibility
• 🐳 Continuous Docker builds on main branch
• 📦 FlakeHub publishing integration
• 🔧 API resilience improvements with fallback channels
• 🛡️ Security fix for PrismJS vulnerability

Installation

pip install mcp-nixos==1.0.2
# or
uv pip install mcp-nixos==1.0.2

Docker Images

docker pull utensils/mcp-nixos:1.0.2
docker pull ghcr.io/utensils/mcp-nixos:1.0.2

See RELEASE_NOTES.md for full details.

What's Changed

• Migrated to FastMCP for improved async performance
• Fixed IntelliJ MCP integration compatibility issues
• Restored minimal main.py implementation
• Updated MCP SDK to 1.12.3

Full Changelog: https://github.com/utensils/mcp-nixos/compare/v1.0.0...v1.0.1