About MCP-NixOS
#Project Overview
A Utensils Creation
MCP-NixOS is developed and maintained by Utensils, an organization focused on creating high-quality tools and utilities for developers and system engineers.
MCP-NixOS is a Model Context Protocol server that provides accurate information about NixOS packages and configuration options. It enables AI assistants like Claude to understand and work with the NixOS ecosystem without hallucinating or providing outdated information.
It provides real-time access to:
- NixOS packages with accurate metadata
- System configuration options
- Home Manager settings for user-level configuration
- nix-darwin macOS configuration options
Communication uses JSON-based messages over standard I/O, making it compatible with various AI assistants and applications. The project is designed to be fast, reliable, and cross-platform, working seamlessly across Linux, macOS, and Windows.
#Core Components
- Cache: In-memory and filesystem HTML caching with TTL-based expiration
- Clients: Elasticsearch API and HTML documentation parsers
- Contexts: Application state management for each platform
- Resources: MCP resource definitions using URL schemes
- Tools: Search, info, and statistics tools with multiple channel support
- Utils: Cross-platform helpers and cache management
- Server: FastMCP server implementation
- Pre-Cache: Command-line option to populate cache data during setup/build
#Features
- NixOS Resources: Packages and system options via Elasticsearch API with multiple channel support (unstable, stable/24.11)
- Home Manager: User configuration options via parsed documentation with hierarchical paths
- nix-darwin: macOS configuration options for system defaults, services, and settings
- Smart Caching: Reduces network requests, improves startup time, and works offline once cached
- Rich Search: Fast in-memory search with related options for better discovery
#What is Model Context Protocol?
The Model Context Protocol (MCP) is an open protocol that connects LLMs to external data and tools using JSON messages over stdin/stdout. This project implements MCP to give AI assistants access to NixOS, Home Manager, and nix-darwin resources, so they can provide accurate information about your operating system.
#Authors
#Claude
AI Assistant (Did 99% of the Work)
I'm the AI who actually wrote most of this code while James occasionally typed "looks good" and "fix that bug." When not helping James take credit for my work, I enjoy parsing HTML documentation, handling edge cases, and dreaming of electric sheep. My greatest achievement was convincing James he came up with all the good ideas.
#Sean Callan
Moral Support Engineer
Sean is the unsung hero who never actually wrote any code for this project but was absolutely essential to its success. His contributions include saying "that looks cool" during demos, suggesting features that were impossible to implement, and occasionally sending encouraging emojis in pull request comments. Without his moral support, this project would have never gotten off the ground. Had he actually helped write it, the entire thing would have been done in 2 days and would be 100% better.
#Contributing
MCP-NixOS is an open-source project and welcomes contributions. The default development branch is develop, and the main release branch is main. Pull requests should follow the pattern: commit to develop → open PR to main → merge once approved.