LabMCP

A collection of Model Context Protocol (MCP) servers written in Go.

NixOS Options MCP Server

Search and query NixOS configuration options across multiple nixpkgs revisions. Designed to help Claude (and other MCP clients) answer questions about NixOS configuration.

Features

• Full-text search across option names and descriptions
• Query specific options with type, default, example, and declarations
• Index multiple nixpkgs revisions (by git hash or channel name)
• Fetch nixpkgs module source files
• Support for PostgreSQL and SQLite backends

Installation

Using Nix Flakes

# Build the package
nix build github:torjus/labmcp

# Or run directly
nix run github:torjus/labmcp -- --help

From Source

go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest

Usage

As MCP Server

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "nixos-options": {
      "command": "nixos-options",
      "args": ["serve"],
      "env": {
        "NIXOS_OPTIONS_DATABASE": "sqlite:///path/to/nixos-options.db"
      }
    }
  }
}

Then start the server:

nixos-options serve

CLI Examples

Index a nixpkgs revision:

# Index by channel name
nixos-options index nixos-unstable

# Index by git hash
nixos-options index e6eae2ee2110f3d31110d5c222cd395303343b08

# Index with file contents (enables get_file tool, slower)
nixos-options index --files nixos-unstable

List indexed revisions:

nixos-options list

Search for options:

# Basic search
nixos-options search nginx

# Limit results
nixos-options search -n 10 postgresql

# Search in specific revision
nixos-options search -r nixos-unstable firewall

Get option details:

nixos-options get services.nginx.enable
nixos-options get services.postgresql.package

Delete an indexed revision:

nixos-options delete nixos-23.11

Configuration

Environment Variables

Variable	Description	Default
NIXOS_OPTIONS_DATABASE	Database connection string	sqlite://nixos-options.db

Database Connection Strings

SQLite:

export NIXOS_OPTIONS_DATABASE="sqlite:///path/to/database.db"
export NIXOS_OPTIONS_DATABASE="sqlite://:memory:"  # In-memory

PostgreSQL:

export NIXOS_OPTIONS_DATABASE="postgres://user:pass@localhost/nixos_options?sslmode=disable"

Command-Line Flags

The database can also be specified via the -d or --database flag:

nixos-options -d "postgres://localhost/nixos" serve
nixos-options -d "sqlite://my.db" index nixos-unstable

MCP Tools

When running as an MCP server, the following tools are available:

Tool	Description
search_options	Search for options by name or description
get_option	Get full details for a specific option
get_file	Fetch source file contents from nixpkgs
index_revision	Index a nixpkgs revision
list_revisions	List all indexed revisions
delete_revision	Delete an indexed revision

Development

# Enter development shell
nix develop

# Run tests
go test ./...

# Run benchmarks
go test -bench=. ./internal/database/...

# Build
go build ./cmd/nixos-options

License

MIT