NixOS MCP Server

A Model Context Protocol (MCP) server that enables searching NixOS configuration options directly from Claude Code.

Features

• Search NixOS configuration options by keyword or phrase
• Returns option names, types, default values, and descriptions
• Pagination support for large result sets
• Built with TypeScript and compatible with Node 24+

Requirements

• Node.js 24 or later (for native TypeScript support)
• npm or yarn

Installation

1. Clone the repository:

cd /path/to/nixos-mcp
npm install

Configuration for Claude Code

To use this MCP server with Claude Code, you need to configure it in Claude Code's configuration file.

Linux/macOS

Edit ~/.config/claude/claude_code_config.json:

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

Windows

Edit %APPDATA%\claude\claude_code_config.json:

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

Restart Claude Code

After adding the configuration, restart Claude Code for the MCP server to be loaded.

Usage

Once configured, you can search NixOS options directly from Claude Code. Here are some example queries:

• "Search for nginx options in NixOS"
• "Find networking firewall configuration options"
• "What NixOS options are available for SSH?"
• "Search for services.postgresql options"

Available Tool

search_nixos_options

Searches NixOS configuration options.

Parameters:

• query (string, required): Search query for NixOS options

  • Examples: "nginx", "networking firewall", "services.postgresql"

• from (number, optional): Starting index for pagination

  • Default: 0
  • Use this to fetch subsequent pages of results

• size (number, optional): Number of results per page

  • Default: 20
  • Range: 1-50

Example:

search_nixos_options {
  query: "nginx services",
  size: 10
}

Response Format:

Found X results for "query":

1. option.name.here
   Type: string
   Default: "default value"
   Description: Description of the option...

2. another.option.name
   Type: boolean
   Default: false
   Description: Another option description...

---
Showing results 1-10 of X total

Development

Run the Server Locally

To test the server without configuring Claude Code:

npm start

Code Quality

Format code:

npm run format

Type check:

npm run typecheck

Features

• Efficient Search: Uses the official NixOS search API endpoint
• NixOS 25.11: Searches against the latest NixOS channel (25.11)
• Type-Safe: Full TypeScript type definitions
• Validated Input: Zod schema validation for all inputs
• Error Handling: Graceful error messages for invalid queries or API issues
• Pagination Support: Handle large result sets efficiently

Architecture

src/
├── index.ts              # MCP server entry point
├── types.ts              # TypeScript type definitions
├── nixos-client.ts       # NixOS API client
└── tools/
    └── search-options.ts # Search tool implementation

Troubleshooting

Server won't start

• Ensure you have Node 24 or later: node --version
• Check that the path to src/index.ts is correct in the configuration
• Look for error messages in Claude Code's MCP server logs

No results found

• Try more specific search terms
• Use common NixOS option names or prefixes (e.g., "services.nginx", "networking")
• Check the NixOS search portal for reference

Connection issues

• Make sure the config file syntax is valid JSON
• Verify the absolute path is correct
• Restart Claude Code after updating the configuration

API Details

This server uses the official NixOS search API:

• Endpoint: https://search.nixos.org/backend/latest-44-nixos-25.11/_search
• Channel: NixOS 25.11
• Type: Only searches configuration options (not packages)

License

ISC