# 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:
```bash
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`:
```json
{
"mcpServers": {
"nixos-search": {
"command": "node",
"args": [
"/absolute/path/to/nixos-mcp/src/index.ts"
]
}
}
}
```
### Windows
Edit `%APPDATA%\claude\claude_code_config.json`:
```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:
```bash
npm start
```
### Code Quality
Format code:
```bash
npm run format
```
Type check:
```bash
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](https://search.nixos.org) 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
