Usage Examples
#Overview
These examples demonstrate how to use MCP-NixOS tools to solve common Nix ecosystem tasks. Each example shows the JSON request format and the corresponding response, helping you understand how to effectively leverage MCP-NixOS in your workflows.
#Configuration
Before using these examples, you'll need to configure your MCP server. Add the following to your MCP configuration file:
{
"mcpServers": {
"nixos": {
"command": "uvx",
"args": ["mcp-nixos"]
}
}
}
This configuration enables your AI assistant to access NixOS package information and configuration options through the MCP protocol. For additional configuration options, see the configuration documentation.
#Example Scenarios
These examples demonstrate practical use cases for MCP-NixOS tools and the type of information they provide. Each example shows the complete workflow from user question to AI response.
#Example 1: PostgreSQL Versions and Configuration
User Prompt
"What PostgreSQL versions are available in NixOS, and what are the configuration options?"
AI Assistant Response:
NixOS provides multiple versions of PostgreSQL:
- PostgreSQL 13 (13.14)
- PostgreSQL 14 (14.10)
- PostgreSQL 15 (15.5)
- PostgreSQL 16 (16.1) - This is the default version
- PostgreSQL 17 (17.0) - Latest version
For configuration, you can use the services.postgresql
module with these key options:
enable
- Enable the PostgreSQL serverpackage
- Select which PostgreSQL version to useauthentication
- Configure client authentication methodsenableTCPIP
- Allow network connections (not just local socket)dataDir
- Specify where to store the database files
This information helps system administrators choose the appropriate PostgreSQL version and configure it according to their specific requirements.
#Example 2: Checking Package Availability
User Prompt
"Is the tldr package available in NixOS, and what variants exist?"
AI Assistant Response:
NixOS provides several implementations of the tldr client:
- The main Python-based
tldr
package - Rust implementations:
tlrc
(official) andtealdeer
(optimized for speed) - Language-specific implementations for Haskell, Emacs Lisp, and R
The main package is available across multiple platforms and provides a simple command-line interface for accessing community-maintained simplified documentation. This is particularly useful for quickly finding common usage examples without having to read through comprehensive man pages.
#Example 3: Validating NixOS Configuration
User Prompt
"Can you validate this Nginx configuration for me?"
AI Assistant Response:
I've analyzed your Nginx configuration and found several issues that need to be corrected:
fastReload
,cacheStrategy
,compressionLevel
,timeoutMs
,requestRateLimiting
, andtlsSettings
are not valid NixOS optionsworkerProcesses
should be"auto"
not"optimal"
- Custom settings should use
extraConfig
andappendHttpConfig
Here's the corrected configuration:
{ config, pkgs, ... }:
{
services.nginx = {
enable = true;
# fastReload is not a valid option, removed
virtualHosts."example.com" = {
enableACME = true;
forceSSL = true;
root = "/var/www/example.com";
locations."/" = {
index = "index.html";
# cacheStrategy is not a valid option
# You can use extraConfig to add caching directives:
extraConfig = ''
expires max;
add_header Cache-Control "public, immutable";
'';
};
locations."/api" = {
proxyPass = "http://localhost:8080";
# compressionLevel is not a valid option
# timeoutMs is not a valid option
# Use extraConfig for these custom settings:
extraConfig = ''
proxy_read_timeout 5s;
gzip on;
gzip_comp_level 9;
'';
};
};
workerProcesses = "auto"; # "optimal" is not valid, use "auto"
# requestRateLimiting is not a valid option block
# Use recommendedProxySettings and limit_req_zone in httpConfig
recommendedProxySettings = true;
appendHttpConfig = ''
limit_req_zone $binary_remote_addr zone=limit:10m rate=100r/s;
limit_req zone=limit burst=20 nodelay;
'';
# tlsSettings is not a valid option block
# Use recommendedTlsSettings instead
recommendedTlsSettings = true;
# For additional TLS settings, use sslCiphers and sslProtocols
sslCiphers = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
sslProtocols = "TLSv1.2 TLSv1.3";
};
}
This corrected configuration follows NixOS best practices for Nginx setup, using standard options and proper syntax for custom settings. The configuration enables HTTPS with ACME (Let's Encrypt), sets up a static file server with caching, configures an API proxy with compression, implements rate limiting, and applies recommended security settings.
#Example 4: Checking Cross-Platform Package Availability
User Prompt
"Is codename goose available in nix packages for mac?"
AI Assistant Response:
While there isn't a package specifically named "codename goose", I found two relevant packages that might match what you're looking for:
goose-cli
(v1.0.15) - An open-source AI agent for coding tasksgoose-lang
(v0.9.2) - A tool that converts Go code to Coq
Both packages are available for macOS, as indicated by the platform identifiers in their metadata:
x86_64-darwin
- Intel-based Macsaarch64-darwin
- Apple Silicon Macs (M1/M2/M3)
If you're looking for the AI coding assistant called "Goose", the goose-cli
package is likely what you want. You can install it on your Mac using:
nix-env -iA nixpkgs.goose-cli # For global installation
# Or in a development shell
nix-shell -p goose-cli
#Example 5: macOS Configuration with nix-darwin
User Prompt
"What all can be configured on macOS when using nix?"
AI Assistant Response:
nix-darwin provides extensive configuration options for macOS, allowing you to manage your system declaratively. Here's a comprehensive overview of what you can configure:
System Configuration
- System Defaults: Appearance (dark mode, accent colors), Dock behavior, Mission Control, keyboard/trackpad settings, Finder preferences, security settings
- Window Managers: Configure tiling window managers like yabai, AeroSpace, and Amethyst
- Networking: Hostname, DNS settings, WireGuard interfaces, firewall rules
Package Management
- Homebrew Integration: Install command-line tools (
brews
), GUI applications (casks
), App Store apps (masApps
) - Nix Packages: System-wide and per-user packages, package overlays
Shell Environment
- Shell Configuration: Bash, Zsh, Fish with customizations for prompts, completions, and plugins
- Environment Variables: System-wide and shell-specific variables, PATH modifications
System Services
- Application Services: Databases (PostgreSQL, MySQL, Redis), web servers, development tools
- macOS Specific: Fonts, launchd services, Spotlight configuration, Time Machine settings
Here's a simple example configuration for customizing macOS with nix-darwin:
{ config, pkgs, ... }:
{
# System defaults
system.defaults.NSGlobalDomain = {
AppleInterfaceStyle = "Dark"; # Enable dark mode
AppleShowScrollBars = "Always"; # Always show scrollbars
NSAutomaticSpellingCorrectionEnabled = false;
};
system.defaults.dock = {
autohide = true; # Auto-hide the dock
orientation = "left"; # Position dock on the left
tilesize = 48; # Icon size
};
# Homebrew packages
homebrew = {
enable = true;
onActivation.autoUpdate = true;
casks = [ "firefox" "visual-studio-code" "iterm2" ];
brews = [ "ripgrep" "fd" "jq" ];
};
# Shell configuration
programs.zsh = {
enable = true;
enableCompletion = true;
enableSyntaxHighlighting = true;
};
# System packages
environment.systemPackages = with pkgs; [
git
neovim
tmux
htop
];
# Window manager
services.yabai = {
enable = true;
config = {
layout = "bsp";
window_gap = 10;
};
};
}
This configuration can be applied by adding it to your ~/.nixpkgs/darwin-configuration.nix
file and running darwin-rebuild switch
. The changes will be applied immediately and persist across reboots, giving you a consistent, reproducible macOS environment.