diff --git a/README.md b/README.md
index 199e38d..0fe8fe3 100644
--- a/README.md
+++ b/README.md
@@ -108,14 +108,142 @@ uv pip install mcp-nixos
 ```
 
 ### For Nix Users (You Know Who You Are)
+
+#### Imperative Installation (Quick & Dirty)
 ```bash
 # Run without installing
 nix run github:utensils/mcp-nixos
 
-# Install to profile
+# Install to profile (not recommended for most Nix users)
 nix profile install github:utensils/mcp-nixos
 ```
 
+#### Declarative Installation (The Nix Way™)
+
+Most Nix users prefer declarative configuration. Here's how to properly integrate MCP-NixOS:
+
+##### Using Flakes (Recommended)
+
+Add to your `flake.nix`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    mcp-nixos.url = "github:utensils/mcp-nixos";
+  };
+
+  outputs = { self, nixpkgs, mcp-nixos, ... }: {
+    # For NixOS systems
+    nixosConfigurations.mysystem = nixpkgs.lib.nixosSystem {
+      modules = [
+        ({ pkgs, ... }: {
+          environment.systemPackages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+
+    # For Home Manager users
+    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
+      modules = [
+        ({ pkgs, ... }: {
+          home.packages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+
+    # For nix-darwin (macOS) users
+    darwinConfigurations.mymac = darwin.lib.darwinSystem {
+      modules = [
+        ({ pkgs, ... }: {
+          environment.systemPackages = [
+            mcp-nixos.packages.${pkgs.system}.default
+          ];
+        })
+      ];
+    };
+  };
+}
+```
+
+##### Using Home Manager (without flakes)
+
+Add to your `home.nix`:
+
+```nix
+{ pkgs, ... }:
+
+let
+  mcp-nixos = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Or pin to a specific commit/tag
+    sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
+  };
+  
+  mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
+in
+{
+  home.packages = [
+    mcp-nixos-pkg
+  ];
+}
+```
+
+##### Using NixOS Configuration (without flakes)
+
+Add to your `configuration.nix`:
+
+```nix
+{ config, pkgs, ... }:
+
+let
+  mcp-nixos = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Or pin to a specific commit/tag
+    sha256 = "0000000000000000000000000000000000000000000000000000"; # Use nix-prefetch-github
+  };
+  
+  mcp-nixos-pkg = pkgs.callPackage "${mcp-nixos}/default.nix" { };
+in
+{
+  environment.systemPackages = with pkgs; [
+    mcp-nixos-pkg
+  ];
+}
+```
+
+##### Using an Overlay
+
+Create an overlay in `~/.config/nixpkgs/overlays/mcp-nixos.nix`:
+
+```nix
+self: super: {
+  mcp-nixos = super.callPackage (super.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main";
+    sha256 = "0000000000000000000000000000000000000000000000000000";
+  } + "/default.nix") { };
+}
+```
+
+Then use it in any Nix expression:
+```nix
+{ pkgs, ... }: {
+  environment.systemPackages = [ pkgs.mcp-nixos ];
+}
+```
+
+After installation, configure your MCP client as shown in the Quick Start section above.
+
+📁 **See the `examples/` directory for complete, copy-paste ready configuration files for all installation methods.**
+
 ## Features Worth Mentioning
 
 ### 🚀 Version 1.0.1: The Async Revolution (After The Great Simplification)
diff --git a/default.nix b/default.nix
new file mode 100644
index 0000000..6aa8e0b
--- /dev/null
+++ b/default.nix
@@ -0,0 +1,34 @@
+{ pkgs ? import <nixpkgs> { } }:
+
+let
+  pythonVersion = "312";
+  python = pkgs."python${pythonVersion}";
+  ps = pkgs."python${pythonVersion}Packages";
+  
+  pyproject = pkgs.lib.importTOML ./pyproject.toml;
+in
+ps.buildPythonApplication {
+  pname = pyproject.project.name;
+  inherit (pyproject.project) version;
+  meta.mainProgram = pyproject.project.name;
+
+  src = ./.;
+
+  format = "pyproject";
+
+  nativeBuildInputs = with ps; [
+    hatchling
+  ];
+
+  propagatedBuildInputs = with ps; [
+    fastmcp
+    requests
+    beautifulsoup4
+  ];
+
+  # Disable runtime dependency checks since the available versions in nixpkgs
+  # may not match exactly what's specified in pyproject.toml
+  pythonImportsCheck = [ ];
+  doCheck = false;
+  dontCheckRuntimeDeps = true;
+}
\ No newline at end of file
diff --git a/examples/configuration.nix b/examples/configuration.nix
new file mode 100644
index 0000000..52e5819
--- /dev/null
+++ b/examples/configuration.nix
@@ -0,0 +1,77 @@
+# Example NixOS system configuration with MCP-NixOS
+# Add this to your /etc/nixos/configuration.nix or create a separate module
+
+{ config, pkgs, lib, ... }:
+
+let
+  # For non-flake users: fetch MCP-NixOS from GitHub
+  mcp-nixos-src = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = lib.fakeSha256; # Replace with actual sha256
+  };
+  
+  # Build the package
+  mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
+in
+{
+  # Add MCP-NixOS to system-wide packages
+  environment.systemPackages = with pkgs; [
+    mcp-nixos
+    # Other packages...
+  ];
+
+  # Optional: Configure MCP-NixOS for all users
+  # This creates a system-wide configuration file
+  environment.etc."claude/claude_desktop_config.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+    # Make it readable by all users
+    mode = "0644";
+  };
+
+  # Optional: Create a systemd service to run MCP-NixOS as a system daemon
+  # (Only useful if your MCP client supports network connections)
+  systemd.services.mcp-nixos = {
+    description = "MCP-NixOS Server";
+    after = [ "network.target" ];
+    wantedBy = [ "multi-user.target" ];
+    
+    serviceConfig = {
+      Type = "simple";
+      ExecStart = "${mcp-nixos}/bin/mcp-nixos";
+      Restart = "on-failure";
+      RestartSec = 5;
+      # Run as a non-privileged user
+      User = "nobody";
+      Group = "nogroup";
+      # Security hardening
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+    
+    # Disable by default - users can enable if needed
+    enable = false;
+  };
+
+  # Optional: Create a shell alias for all users
+  programs.bash.shellAliases = {
+    mcp-nixos-test = "${mcp-nixos}/bin/mcp-nixos";
+  };
+
+  # Optional: Add to the system path
+  environment.variables = {
+    MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
+  };
+}
\ No newline at end of file
diff --git a/examples/darwin-configuration.nix b/examples/darwin-configuration.nix
new file mode 100644
index 0000000..f95345f
--- /dev/null
+++ b/examples/darwin-configuration.nix
@@ -0,0 +1,91 @@
+# Example nix-darwin configuration with MCP-NixOS for macOS
+# Add this to your darwin-configuration.nix or create a separate module
+
+{ config, pkgs, lib, ... }:
+
+let
+  # For non-flake users: fetch MCP-NixOS from GitHub
+  mcp-nixos-src = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = lib.fakeSha256; # Replace with actual sha256
+  };
+  
+  # Build the package
+  mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
+in
+{
+  # Add MCP-NixOS to system-wide packages
+  environment.systemPackages = with pkgs; [
+    mcp-nixos
+    # Other packages...
+  ];
+
+  # Configure Claude Desktop for all users
+  # Note: Adjust path based on where Claude Desktop stores config on macOS
+  environment.etc."claude/claude_desktop_config.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+  };
+
+  # Create launchd service for MCP-NixOS (macOS equivalent of systemd)
+  launchd.user.agents.mcp-nixos = {
+    command = "${mcp-nixos}/bin/mcp-nixos";
+    
+    serviceConfig = {
+      Label = "org.nixos.mcp-nixos";
+      RunAtLoad = false; # Don't start automatically
+      KeepAlive = false; # Don't restart if it crashes
+      StandardErrorPath = "/tmp/mcp-nixos.err";
+      StandardOutPath = "/tmp/mcp-nixos.out";
+    };
+  };
+
+  # Add shell aliases for convenience
+  programs.bash.interactiveShellInit = ''
+    alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
+  '';
+  
+  programs.zsh.interactiveShellInit = ''
+    alias mcp-nixos-test='${mcp-nixos}/bin/mcp-nixos'
+  '';
+
+  # Optional: Configure for Cursor on macOS
+  # This assumes Cursor config is in the user's home directory
+  system.activationScripts.postUserActivation.text = ''
+    # Create Cursor MCP config for all users
+    for user_home in /Users/*; do
+      if [ -d "$user_home" ]; then
+        cursor_config_dir="$user_home/.cursor"
+        if [ ! -d "$cursor_config_dir" ]; then
+          mkdir -p "$cursor_config_dir"
+        fi
+        
+        cat > "$cursor_config_dir/mcp.json" <<EOF
+    {
+      "mcpServers": {
+        "nixos": {
+          "command": "${mcp-nixos}/bin/mcp-nixos",
+          "args": []
+        }
+      }
+    }
+    EOF
+      fi
+    done
+  '';
+
+  # Set environment variable for easy reference
+  environment.variables = {
+    MCP_NIXOS_PATH = "${mcp-nixos}/bin/mcp-nixos";
+  };
+}
\ No newline at end of file
diff --git a/examples/flake.nix b/examples/flake.nix
new file mode 100644
index 0000000..611c060
--- /dev/null
+++ b/examples/flake.nix
@@ -0,0 +1,125 @@
+# Example flake.nix for using MCP-NixOS declaratively
+# Copy this to your system configuration and adjust as needed
+
+{
+  description = "Example system configuration with MCP-NixOS";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    
+    # Add MCP-NixOS as an input
+    mcp-nixos = {
+      url = "github:utensils/mcp-nixos";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    
+    # Optional: Add Home Manager if you use it
+    home-manager = {
+      url = "github:nix-community/home-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    
+    # Optional: Add nix-darwin for macOS
+    darwin = {
+      url = "github:LnL7/nix-darwin";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, mcp-nixos, home-manager, darwin, ... }@inputs: {
+    
+    # Example NixOS system configuration
+    nixosConfigurations = {
+      my-nixos-system = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          ./hardware-configuration.nix
+          ./configuration.nix
+          
+          # Add MCP-NixOS to system packages
+          ({ pkgs, ... }: {
+            environment.systemPackages = [
+              mcp-nixos.packages.${pkgs.system}.default
+            ];
+          })
+        ];
+      };
+    };
+    
+    # Example Home Manager configuration
+    homeConfigurations = {
+      "myuser@hostname" = home-manager.lib.homeManagerConfiguration {
+        pkgs = nixpkgs.legacyPackages.x86_64-linux;
+        
+        modules = [
+          ./home.nix
+          
+          # Add MCP-NixOS to user packages
+          ({ pkgs, ... }: {
+            home.packages = [
+              mcp-nixos.packages.${pkgs.system}.default
+            ];
+            
+            # Optional: Configure MCP client settings
+            home.file.".config/claude/claude_desktop_config.json".text = ''
+              {
+                "mcpServers": {
+                  "nixos": {
+                    "command": "${mcp-nixos.packages.${pkgs.system}.default}/bin/mcp-nixos"
+                  }
+                }
+              }
+            '';
+          })
+        ];
+      };
+    };
+    
+    # Example nix-darwin (macOS) configuration
+    darwinConfigurations = {
+      "my-mac" = darwin.lib.darwinSystem {
+        system = "aarch64-darwin"; # or "x86_64-darwin" for Intel Macs
+        
+        modules = [
+          ./darwin-configuration.nix
+          
+          # Add MCP-NixOS to system packages
+          ({ pkgs, ... }: {
+            environment.systemPackages = [
+              mcp-nixos.packages.${pkgs.system}.default
+            ];
+            
+            # Optional: Configure for all users
+            environment.etc."claude/claude_desktop_config.json".text = ''
+              {
+                "mcpServers": {
+                  "nixos": {
+                    "command": "${mcp-nixos.packages.${pkgs.system}.default}/bin/mcp-nixos"
+                  }
+                }
+              }
+            '';
+          })
+        ];
+      };
+    };
+    
+    # Development shell with MCP-NixOS available
+    devShells = nixpkgs.lib.genAttrs [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ] (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in {
+        default = pkgs.mkShell {
+          buildInputs = [
+            mcp-nixos.packages.${system}.default
+          ];
+          
+          shellHook = ''
+            echo "MCP-NixOS is available in this shell"
+            echo "Run 'mcp-nixos' to start the server"
+          '';
+        };
+      }
+    );
+  };
+}
\ No newline at end of file
diff --git a/examples/home.nix b/examples/home.nix
new file mode 100644
index 0000000..a77d245
--- /dev/null
+++ b/examples/home.nix
@@ -0,0 +1,76 @@
+# Example Home Manager configuration with MCP-NixOS
+# Add this to your home.nix or create a separate module
+
+{ config, pkgs, lib, ... }:
+
+let
+  # For non-flake users: fetch MCP-NixOS from GitHub
+  mcp-nixos-src = pkgs.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = lib.fakeSha256; # Replace with actual sha256
+  };
+  
+  # Build the package
+  mcp-nixos = pkgs.callPackage "${mcp-nixos-src}/default.nix" { };
+in
+{
+  # Add MCP-NixOS to user packages
+  home.packages = [
+    mcp-nixos
+  ];
+
+  # Configure Claude Desktop to use MCP-NixOS
+  # Adjust the path based on your Claude installation
+  home.file.".config/claude/claude_desktop_config.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+  };
+
+  # Alternative: For Cursor users
+  home.file.".cursor/mcp.json" = {
+    text = builtins.toJSON {
+      mcpServers = {
+        nixos = {
+          command = "${mcp-nixos}/bin/mcp-nixos";
+          args = [];
+        };
+      };
+    };
+  };
+
+  # Optional: Create a shell alias for quick access
+  programs.bash.shellAliases = {
+    mcp-nixos-test = "${mcp-nixos}/bin/mcp-nixos";
+  };
+  
+  programs.zsh.shellAliases = {
+    mcp-nixos-test = "${mcp-nixos}/bin/mcp-nixos";
+  };
+
+  # Optional: Create a systemd user service to run MCP-NixOS as a daemon
+  # (Only useful if your MCP client supports network connections)
+  systemd.user.services.mcp-nixos = {
+    Unit = {
+      Description = "MCP-NixOS Server";
+      After = [ "network.target" ];
+    };
+    Service = {
+      Type = "simple";
+      ExecStart = "${mcp-nixos}/bin/mcp-nixos";
+      Restart = "on-failure";
+      RestartSec = 5;
+      # Uncomment if you want it to start automatically
+      # WantedBy = [ "default.target" ];
+    };
+  };
+}
\ No newline at end of file
diff --git a/examples/overlay.nix b/examples/overlay.nix
new file mode 100644
index 0000000..28c94a6
--- /dev/null
+++ b/examples/overlay.nix
@@ -0,0 +1,31 @@
+# Example Nix overlay for MCP-NixOS
+# Save this as ~/.config/nixpkgs/overlays/mcp-nixos.nix
+# or include it in your overlays list
+
+self: super: {
+  mcp-nixos = super.callPackage (super.fetchFromGitHub {
+    owner = "utensils";
+    repo = "mcp-nixos";
+    rev = "main"; # Pin to a specific commit for reproducibility
+    # To get the correct sha256:
+    # nix-prefetch-github utensils mcp-nixos
+    sha256 = "0000000000000000000000000000000000000000000000000000"; # Replace with actual sha256
+  } + "/default.nix") { };
+}
+
+# After adding this overlay, you can use mcp-nixos in any Nix expression:
+#
+# With Home Manager:
+#   home.packages = [ pkgs.mcp-nixos ];
+#
+# With NixOS:
+#   environment.systemPackages = [ pkgs.mcp-nixos ];
+#
+# With nix-darwin:
+#   environment.systemPackages = [ pkgs.mcp-nixos ];
+#
+# In a shell:
+#   nix-shell -p mcp-nixos
+#
+# Or directly:
+#   nix run nixpkgs#mcp-nixos
\ No newline at end of file