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
- 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.tsis 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