NixOS

You run a focused MCP server that lets you search NixOS configuration options from your editor or tooling. It returns option names, types, default values, and descriptions, with pagination for large result sets. You can start it locally and connect it via an MCP client to perform fast, typed queries against the NixOS options catalog.

How to use

You connect to a local MCP server from your MCP client or editor. Use the provided search tool to look up NixOS configuration options by keyword or phrase. You can refine results with pagination and receive detailed option information including the option path, data type, default value, and a brief description. Typical workflows include finding options for a specific service (for example nginx or ssh), or discovering related configuration keys by prefix like networking or services.

How to install

Prerequisites you need before installing the MCP server are:

• Node.js 24 or later
• npm or yarn

Install and run the MCP server locally with these steps:

# Step 1: Install dependencies
npm install

# Step 2: Start the MCP server
npm start

Configuration and usage notes

If you want to use Claude Code or another MCP client, configure the MCP server as a local stdio process. The client launches the server by running node and pointing to the MCP entry script. You can set this up with a configuration like the one below, specifying the exact path to the server entry. Replace the absolute path with the location where you cloned or placed the MCP server.

{
  "mcpServers": {
    "nixos_search": {
      "command": "node",
      "args": [
        "/absolute/path/to/nixos-mcp/src/index.ts"
      ]
    }
  }
}

After adding the configuration, restart your MCP client to load the new server. With this setup, you can issue queries such as finding nginx options or SSH-related configurations and receive structured results.

Additional notes

Key details you should know about this MCP server include the following capabilities and constraints:

• Search NixOS configuration options with a typed, structured response that includes option name, type, default value, and description
• Support for paging large result sets to keep responses manageable
• Built with TypeScript and compatible with Node 24+
• Uses a single stdio connection when run locally via a client, with a node process executing the MCP entry script

You can switch to a remote HTTP-based approach if you expose the server through a URL, but this guide focuses on running the MCP server locally for development and testing.

Troubleshooting

If the server won’t start, check these common issues:

• Verify you have Node.js 24 or later by running node --version
• Confirm the path to the MCP entry script is correct in your client configuration
• Check the MCP server logs in your client or terminal for error messages

If you don’t see results, try more specific queries or prefix-based searches such as networking or services.nginx. Ensure the client’s pagination parameters are within supported limits (size 1–50).

API and data source context

This MCP server enables searches against the NixOS configuration options dataset, returning option names, types, default values, and descriptions. It is designed to be queried from MCP clients and editors to streamline configuration discovery and learning.

Available tools

search_nixos_options

Searches NixOS configuration options. Accepts a query, optional starting index, and page size to return a paginated list of matching options with details for each option.