{"id":26827761,"url":"https://github.com/utensils/mcp-nixos","last_synced_at":"2026-08-27T23:55:36.605Z","repository":{"id":283416218,"uuid":"951693330","full_name":"utensils/mcp-nixos","owner":"utensils","description":"MCP-NixOS - Model Context Protocol Server for NixOS resources","archived":false,"fork":false,"pushed_at":"2026-08-12T17:12:41.000Z","size":2712,"stargazers_count":799,"open_issues_count":1,"forks_count":44,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-08-19T16:48:05.182Z","etag":null,"topics":["ai-assistant","ai-integration","ai-tools","anthropic","claude","developer-tools","devops-tools","fastmcp","llm-tools","mcp","model-context-protocol","nix","nix-options","nix-packages","nix-search","nixos","package-search","python","sre-tools"],"latest_commit_sha":null,"homepage":"https://mcp-nixos.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utensils.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","claude":"CLAUDE.md","gemini":null,"cursor":null,"copilot":".github/copilot-instructions.md","dco":null,"cla":null,"disclosure":null}},"created_at":"2025-03-20T05:05:00.000Z","updated_at":"2026-08-19T13:41:58.000Z","dependencies_parsed_at":"2025-04-20T09:31:40.621Z","dependency_job_id":"44db47ba-f7fe-467f-8186-50acad94d8d0","html_url":"https://github.com/utensils/mcp-nixos","commit_stats":null,"previous_names":["utensils/nixmcp","utensils/mcp-nixos"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/utensils/mcp-nixos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utensils%2Fmcp-nixos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utensils%2Fmcp-nixos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utensils%2Fmcp-nixos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utensils%2Fmcp-nixos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utensils","download_url":"https://codeload.github.com/utensils/mcp-nixos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utensils%2Fmcp-nixos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36947771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","ai-integration","ai-tools","anthropic","claude","developer-tools","devops-tools","fastmcp","llm-tools","mcp","model-context-protocol","nix","nix-options","nix-packages","nix-search","nixos","package-search","python","sre-tools"],"created_at":"2025-03-30T12:17:00.621Z","updated_at":"2026-08-27T23:55:36.599Z","avatar_url":"https://github.com/utensils.png","language":"Python","funding_links":[],"categories":["Developer Tools","Data Access \u0026 Integration MCP Servers","MCP","📚 Projects (1974 total)","پیاده‌سازی‌های سرور","HTML","APIs and HTTP Requests","Development","MCP Servers","📦 Other","Python","MCP Servers \u0026 Protocol","💻 Developer Tools (164 servers)","Server Implementations"],"sub_categories":["CI/CD \u0026 DevOps","MCP Servers","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eابزارهای توسعه‌دهنده","How to Submit","Cloud \u0026 DevOps","Discovery","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eDeveloper Tools"],"readme":"# MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names\n\n[![MCP Toplist](https://mcptoplist.com/badge/glama%2Futensils%2Fmcp-nixos.svg)](https://mcptoplist.com/server/glama%2Futensils%2Fmcp-nixos)\n\n[![CI](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml/badge.svg)](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/utensils/mcp-nixos/graph/badge.svg?token=kdcbgvq4Bh)](https://codecov.io/gh/utensils/mcp-nixos)\n[![PyPI](https://img.shields.io/pypi/v/mcp-nixos.svg)](https://pypi.org/project/mcp-nixos/)\n[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/utensils/mcp-nixos/badge)](https://flakehub.com/flake/utensils/mcp-nixos)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/utensils/mcp-nixos?utm_source=oss\u0026utm_medium=github\u0026utm_campaign=utensils%2Fmcp-nixos\u0026labelColor=171717\u0026color=FF570A\u0026link=https%3A%2F%2Fcoderabbit.ai\u0026label=CodeRabbit+Reviews)\n[![Built with Claude](https://img.shields.io/badge/Built%20with-Claude-D97757?logo=claude\u0026logoColor=white)](https://claude.ai)\n\n## Quick Start\n\n**🚨 No Nix/NixOS Required!** Works on any system - Windows, macOS, Linux. You're just querying APIs.\n\n### Option 1: uvx (Recommended)\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos\u0026config=eyJjb21tYW5kIjoidXZ4IG1jcC1uaXhvcyJ9)\n\n```json\n{\n  \"mcpServers\": {\n    \"nixos\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nixos\"]\n    }\n  }\n}\n```\n\n### Option 2: Nix\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos\u0026config=eyJjb21tYW5kIjoibml4IHJ1biBnaXRodWI6dXRlbnNpbHMvbWNwLW5peG9zIC0tIn0%3D)\n\n```json\n{\n  \"mcpServers\": {\n    \"nixos\": {\n      \"command\": \"nix\",\n      \"args\": [\"run\", \"github:utensils/mcp-nixos\", \"--\"]\n    }\n  }\n}\n```\n\n### Option 3: Docker\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos\u0026config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCJnaGNyLmlvL3V0ZW5zaWxzL21jcC1uaXhvcyJdfQ%3D%3D)\n\n```json\n{\n  \"mcpServers\": {\n    \"nixos\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"ghcr.io/utensils/mcp-nixos\"]\n    }\n  }\n}\n```\n\nYour AI now has access to real NixOS data instead of making things up. You're welcome.\n\n### Option 4: HTTP (Remote MCP)\n\nFastMCP supports running this server over HTTP at a URL (the MCP endpoint defaults to `/mcp`).\n\n```bash\n# Run an HTTP MCP server at http://127.0.0.1:8000/mcp\nMCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos\n```\n\nSTDIO (default):\n\n```bash\nMCP_NIXOS_TRANSPORT=stdio mcp-nixos\n```\n\nCustom path:\n\n```bash\nMCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos\n```\n\nStateless HTTP (disables per-client session state):\n\n```bash\nMCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos\n```\n\n### Option 5: Pi Coding Agent\n\n[Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) does not speak MCP natively. Two supported paths:\n\n**A. pi-mcp-adapter (recommended — speaks MCP, single source of truth):**\n\n```bash\npi install npm:pi-mcp-adapter\n```\n\nThen add to `~/.pi/agent/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nixos\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-nixos\"],\n      \"lifecycle\": \"lazy\"\n    }\n  }\n}\n```\n\n**B. Project-local extension (clone + run):** this repo ships `.pi/extensions/mcp-nixos.ts`, auto-loaded when you run `pi` in the cloned repo. Optional: `cd .pi \u0026\u0026 npm install` for editor type resolution. Pi runs it either way.\n\n## What Is This?\n\nAn MCP server providing accurate, real-time information about:\n\n- **NixOS packages** - 130K+ packages that actually exist\n- **NixOS options** - 23K+ ways to configure your system\n- **Home Manager** - 5K+ options for dotfile enthusiasts\n- **nix-darwin** - 1K+ macOS settings Apple doesn't document\n- **Nixvim** - 5K+ options for Neovim configuration via [NuschtOS search](https://github.com/NuschtOS/search)\n- **NVF** - 2.4K+ Neovim options from its [published unstable documentation](https://nvf.notashelf.dev/options.html)\n- **FlakeHub** - 600+ flakes from [FlakeHub.com](https://flakehub.com) registry\n- **Noogle** - 2K+ Nix functions with type signatures via [noogle.dev](https://noogle.dev)\n- **NixOS Wiki** - Community documentation and guides from [wiki.nixos.org](https://wiki.nixos.org)\n- **nix.dev** - Official Nix tutorials and guides from [nix.dev](https://nix.dev)\n- **Package versions** - Historical versions with commit hashes via [NixHub.io](https://www.nixhub.io)\n- **Binary cache status** - Check if packages are cached on cache.nixos.org with download sizes\n- **Local flake inputs** - Explore your pinned flake dependencies directly from the Nix store (requires Nix)\n\n## The Tools\n\nJust two. We consolidated 17 tools into 2 because your AI's context window isn't infinite.\n\n**~1,030 tokens total.** That's it. While other MCP servers are hogging your context like it's Black Friday, we're sipping minimalist tea in the corner. Your AI gets NixOS superpowers without the bloat.\n\n### `nix` - Unified Query Tool\n\nOne tool to rule them all:\n\n```text\nnix(action, query, source, type, channel, limit)\n```\n\n| Action | What it does |\n|--------|-------------|\n| `search` | Search packages, options, programs, or flakes |\n| `info` | Get detailed info about a package or option |\n| `stats` | Get counts and categories |\n| `browse` | Browse Home Manager, Darwin, Nixvim, NVF, or Noogle by prefix (legacy alias: `options`) |\n| `channels` | List available NixOS channels |\n| `flake-inputs` | Explore local flake inputs from Nix store |\n| `cache` | Check binary cache status for packages |\n\n| Source | What it queries |\n|--------|----------------|\n| `nixos` | Packages, options, programs |\n| `home-manager` | Home Manager options |\n| `darwin` | nix-darwin options |\n| `flakes` | Community flakes (search.nixos.org) |\n| `flakehub` | FlakeHub registry (flakehub.com) |\n| `nixvim` | Nixvim Neovim configuration options |\n| `nvf` | NVF Neovim configuration options (latest unstable docs) |\n| `noogle` | Nix function signatures and docs (noogle.dev) |\n| `wiki` | NixOS Wiki articles (wiki.nixos.org) |\n| `nix-dev` | Official Nix documentation (nix.dev) |\n| `nixhub` | Package metadata and store paths (nixhub.io) |\n\nNVF results use canonical `vim.*` option paths. Queries may also use the shorthand\n`programs.nvf.vim.*` or the NixOS/Home Manager module path\n`programs.nvf.settings.vim.*`; both are normalized automatically.\n\n**Examples:**\n\n```python\n# Search NixOS packages\nnix(action=\"search\", query=\"firefox\", source=\"nixos\", type=\"packages\")\n\n# Get package info\nnix(action=\"info\", query=\"firefox\", source=\"nixos\", type=\"package\")\n\n# Search Home Manager options\nnix(action=\"search\", query=\"git\", source=\"home-manager\")\n\n# Browse darwin options\nnix(action=\"browse\", source=\"darwin\", query=\"system.defaults\")\n\n# Search Nixvim options\nnix(action=\"search\", query=\"telescope\", source=\"nixvim\")\n\n# Get Nixvim option info\nnix(action=\"info\", query=\"plugins.telescope.enable\", source=\"nixvim\")\n\n# Search NVF options\nnix(action=\"search\", query=\"vim.languages.nix\", source=\"nvf\")\n\n# Get NVF option info using a module wrapper path\nnix(action=\"info\", query=\"programs.nvf.settings.vim.languages.nix.enable\", source=\"nvf\")\n\n# Browse NVF options below a prefix\nnix(action=\"browse\", query=\"programs.nvf.vim.languages.nix\", source=\"nvf\")\n\n# Search FlakeHub\nnix(action=\"search\", query=\"nixpkgs\", source=\"flakehub\")\n\n# Get FlakeHub flake info\nnix(action=\"info\", query=\"NixOS/nixpkgs\", source=\"flakehub\")\n\n# Search Noogle for Nix functions\nnix(action=\"search\", query=\"mapAttrs\", source=\"noogle\")\n\n# Get Noogle function info\nnix(action=\"info\", query=\"lib.attrsets.mapAttrs\", source=\"noogle\")\n\n# Browse Noogle function categories\nnix(action=\"browse\", source=\"noogle\", query=\"lib.strings\")\n\n# Search NixOS Wiki\nnix(action=\"search\", query=\"nvidia\", source=\"wiki\")\n\n# Get Wiki page info\nnix(action=\"info\", query=\"Flakes\", source=\"wiki\")\n\n# Search nix.dev documentation\nnix(action=\"search\", query=\"packaging tutorial\", source=\"nix-dev\")\n\n# Search NixHub for package metadata\nnix(action=\"search\", query=\"nodejs\", source=\"nixhub\")\n\n# Get detailed package info from NixHub (license, homepage, store paths)\nnix(action=\"info\", query=\"python\", source=\"nixhub\")\n\n# Check binary cache status\nnix(action=\"cache\", query=\"hello\")\n\n# Check cache for specific version\nnix(action=\"cache\", query=\"python\", version=\"3.12.0\")\n\n# Check cache for specific system\nnix(action=\"cache\", query=\"firefox\", system=\"x86_64-linux\")\n\n# Get stats\nnix(action=\"stats\", source=\"nixos\", channel=\"stable\")\n\n# List local flake inputs (requires Nix)\nnix(action=\"flake-inputs\", type=\"list\")\n\n# Browse files in a flake input\nnix(action=\"flake-inputs\", type=\"ls\", query=\"nixpkgs:pkgs/by-name\")\n\n# Read a file from a flake input\nnix(action=\"flake-inputs\", type=\"read\", query=\"nixpkgs:flake.nix\")\n```\n\n### `nix_versions` - Package Version History\n\nFind historical versions with nixpkgs commit hashes. Output includes:\n- Package metadata (license, homepage, programs) when available\n- Platform availability per version (Linux/macOS)\n- Nixpkgs commit hash for reproducible builds\n- Attribute path for Nix expressions\n\n```python\nnix_versions(package, version, limit)\n```\n\n**Examples:**\n\n```python\n# List recent versions with metadata\nnix_versions(package=\"python\", limit=5)\n\n# Find specific version\nnix_versions(package=\"nodejs\", version=\"20.0.0\")\n```\n\n## Installation\n\n**You DON'T need Nix installed.** This runs anywhere Python runs.\n\n```bash\n# Run directly (no install)\nuvx mcp-nixos\n\n# Or install\npip install mcp-nixos\n```\n\nFor Nix users:\n\n```bash\nnix run github:utensils/mcp-nixos\nnix profile install github:utensils/mcp-nixos\n```\n\n### Declarative Installation (NixOS / Home Manager / nix-darwin)\n\nmcp-nixos is available in [nixpkgs](https://search.nixos.org/packages?channel=unstable\u0026show=mcp-nixos\u0026query=mcp-nixos):\n\n```nix\n# NixOS (configuration.nix)\nenvironment.systemPackages = [ pkgs.mcp-nixos ];\n\n# Home Manager (home.nix)\nhome.packages = [ pkgs.mcp-nixos ];\n\n# nix-darwin (darwin-configuration.nix)\nenvironment.systemPackages = [ pkgs.mcp-nixos ];\n```\n\nOr use the flake directly with the provided overlay:\n\n```nix\n# flake.nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    mcp-nixos.url = \"github:utensils/mcp-nixos\";\n  };\n\n  outputs = { self, nixpkgs, mcp-nixos, ... }: {\n    # Example: NixOS configuration\n    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {\n      system = \"x86_64-linux\";\n      modules = [{\n        nixpkgs.overlays = [ mcp-nixos.overlays.default ];\n        environment.systemPackages = [ pkgs.mcp-nixos ];\n      }];\n    };\n\n    # Example: Home Manager standalone\n    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {\n      pkgs = import nixpkgs {\n        system = \"x86_64-linux\";\n        overlays = [ mcp-nixos.overlays.default ];\n      };\n      modules = [{\n        home.packages = [ pkgs.mcp-nixos ];\n      }];\n    };\n  };\n}\n```\n\n## Development\n\n```bash\nnix develop          # Enter dev shell\nnix build            # Build package\npytest tests/        # Run tests\nruff check .         # Lint\nruff format .        # Format\nmypy mcp_nixos/      # Type check\n```\n\n## Acknowledgments\n\n- **[NixHub.io](https://www.nixhub.io)** - Package version history\n- **[search.nixos.org](https://search.nixos.org)** - Official NixOS search\n- **[FlakeHub](https://flakehub.com)** - Flake registry by Determinate Systems\n- **[Jetify](https://www.jetify.com)** - Creators of Devbox and NixHub\n- **[Noogle](https://noogle.dev)** - Nix function search engine\n- **[NuschtOS](https://github.com/NuschtOS/search)** - Static option search infrastructure powering Nixvim support\n- **[Nixvim](https://github.com/nix-community/nixvim)** - Neovim configuration framework for Nix\n- **[NVF](https://github.com/NotAShelf/nvf)** - Neovim configuration framework and published option catalogue\n\n## License\n\nMIT - Because sharing is caring.\n\n---\n\n*Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futensils%2Fmcp-nixos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futensils%2Fmcp-nixos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futensils%2Fmcp-nixos/lists"}