v2.3.0: HTTP Transport & Modular Architecture

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.

v2.2.0: Documentation Sources & Flake Inputs

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.

v2.1.1: Stable Python Compatibility

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.

v2.1.0: Pure Nix Flake

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.

v2.0.0: The Great Consolidation

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

v1.1.0: NixOS 25.11 Stable

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.

v1.0.3: Encoding Fix

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.

v1.0.2: Infrastructure Improvements

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.

v1.0.1 - FastMCP Migration & IntelliJ Fixes

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: v1.0.0...v1.0.1

Release v1.0.0

Overview

MCP-NixOS v1.0.0 is a complete rewrite that proves less is more. We've drastically simplified the codebase while maintaining 100% functionality and adding new features. This isn't just a refactor—it's a masterclass in minimalism.

Changes in v1.0.0

🎯 The Nuclear Option

• Complete Rewrite: Drastically simplified the entire codebase
• Stateless Operation: No more cache directories filling up your disk
• Direct API Calls: Removed all abstraction layers—now it's just functions doing their job
• Simplified Dependencies: Reduced from 5 to 3 core dependencies (40% reduction)
• Two-File Implementation: Everything you need in just server.py and __main__.py
• Resolves #22: Completely eliminated pickle usage and the entire cache layer

🚀 Major Improvements

• Plain Text Output: All responses now return human-readable plain text (no XML!)
• NixHub Integration: Added package version history tools
  • nixhub_package_versions: Get version history with nixpkgs commits
  • nixhub_find_version: Smart search for specific versions
• Dynamic Channel Resolution: Auto-discovers current stable channel
• Enhanced Error Messages: Suggestions when exact matches fail
• Flake Search: Added deduplicated flake package search
• Better Stats: Accurate statistics for all tools
• Zero Configuration: Removed all the config options you weren't using anyway
• Faster Startup: No cache initialization, no state management, just pure functionality
• 100% Test Coverage: Comprehensive test suite ensures everything works as advertised

💥 Breaking Changes

• No More Caching: All operations are now stateless (your internet better be working)
• Environment Variables Removed: Only ELASTICSEARCH_URL remains
• No Pre-Cache Option: The --pre-cache flag is gone (along with the cache itself)
• No Interactive Shell: The deprecated CLI has been completely removed

🧹 What We Removed

• cache/ directory - Complex caching that nobody understood
• clients/ directory - Abstract interfaces that abstracted nothing
• contexts/ directory - Context managers for contexts that didn't exist
• resources/ directory - MCP resource definitions (now inline)
• tools/ directory - Tool implementations (now in server.py)
• utils/ directory - "Utility" functions that weren't
• 45 files of over-engineered complexity

📊 The Numbers

• Before: Many files with layers of abstraction
• After: Just 2 core files that matter
• Result: Dramatically less code, zero reduction in functionality, more features added

Installation

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

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

# Install with uvx
uvx mcp-nixos==1.0.0

Migration Guide

If you're upgrading from v0.x:

1. Remove cache-related environment variables - They don't do anything anymore
2. Remove --pre-cache from any scripts - It's gone
3. That's it - Everything else just works

Why This Matters

This release demonstrates that most "enterprise" code is just complexity for complexity's sake. By removing abstractions, caching layers, and "design patterns," we've created something that:

• Is easier to understand
• Has fewer bugs (less code = less bugs)
• Starts faster
• Uses less memory
• Is more reliable

Sometimes the best code is the code you delete.

Contributors

• James Brink (@utensils) - Chief Code Deleter

---