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.