mcp-servers-nix

The passwordCommand option is a secure way to integrate with password managers (like pass or gh auth) to retrieve sensitive credentials at runtime. This is handled via a wrapper regardless of the server's flavor.

There are two ways to specify it:

1. As a string: The command must output in KEY=VALUE format. Example: "pass mcp-server" (assuming pass outputs TOKEN=xyz).

2. As an attribute set: Keys are the target environment variable names, and values are lists of strings representing the command to run to get the value.

Example (Attribute Set):

passwordCommand = {
  GITHUB_PERSONAL_ACCESS_TOKEN = [ "gh" "auth" "token" ];
};

programs.github.passwordCommand = {
  GITHUB_PERSONAL_ACCESS_TOKEN = [
    "gh"
    "auth"
    "token"
  ];
};

The passwordCommand option allows you to integrate with password managers to securely inject environment variables. It can be specified in two ways:

1. As a string: The command must output text in the KEY=VALUE format. Each line will be exported as an environment variable. Example: "pass mcp-server" (assuming pass outputs TOKEN=123)

2. As an attribute set: Keys are the desired environment variable names, and values are lists of strings representing the command to execute to fetch the value. Example: { GITHUB_TOKEN = [ "gh" "auth" "token" ]; }

passwordCommand is always handled via the wrapper regardless of the selected flavor.

# Using an attribute set for specific keys
programs.netdata.passwordCommand = {
  GITHUB_PERSONAL_ACCESS_TOKEN = [
    "gh"
    "auth"
    "token"
  ];
};

When configuring MCP servers via Nix, avoid hardcoding sensitive credentials in the env attribute set. Because files in /nix/store are world-readable, any secrets placed there are exposed.

Recommended approach: Use the envFile option to point to an absolute path of an .env file containing your secrets.

Note for VSCode users: When the flavor is set to vscode, the environment file is passed directly as a parameter instead of being wrapped by default.

The module system provides a declarative way to configure MCP servers using Nix. The core workflow involves:

1. mkConfig: Evaluates your module configuration and produces a configuration file in JSON, YAML, or TOML format.
2. programs.<name>.enable: Activates a pre-configured module for a specific MCP server (e.g., programs.filesystem.enable = true).
3. flavor: Determines the output key structure to match specific clients (e.g., mcpServers for Claude, mcp.servers for VS Code).
4. format: Determines the output file format (JSON, YAML, or TOML).

For detailed option definitions, refer to the Module Options Reference and Configuration Reference.

The passwordCommand option is a secure way to integrate with password managers (like pass or gh auth) to retrieve sensitive environment variables at runtime. This is handled via a wrapper regardless of the server's flavor.

There are two ways to specify it:

1. As a string: The command must output in KEY=VALUE format. The output will be exported as environment variables. Example: "pass mcp-server" (assuming the command outputs API_KEY=123).

2. As an attribute set: Keys are the desired environment variable names, and values are lists of strings representing the command to execute to retrieve the value.

Example (Attribute Set):

passwordCommand = {
  GITHUB_PERSONAL_ACCESS_TOKEN = [ "gh" "auth" "token" ];
};

To make an MCP server package available in your environment, you can install it using either the classic nix-env method or the modern nix profile method if you are using flakes.

# Without flakes
nix-env -f https://github.com/natsukium/mcp-servers-nix/archive/main.tar.gz -iA mcp-server-fetch

# Using flakes
nix profile install github:natsukium/mcp-servers-nix#mcp-server-fetch

You can add all available MCP server packages to your nixpkgs instance by adding the provided overlay to your configuration.nix or home.nix. This allows you to manage MCP servers as standard packages through pkgs.

Classic configuration

Use builtins.fetchTarball to import the overlay.

Flake configuration

Use the overlay path provided by your flake input (e.g., mcp-servers-nix.overlays.default).

# In your configuration.nix or home.nix
{
  nixpkgs.overlays = [
    # classic
    (import (builtins.fetchTarball "https://github.com/natsukium/mcp-servers-nix/archive/main.tar.gz")).overlays.default
    # or with flakes
    # mcp-servers-nix.overlays.default
  ];

  # Then install packages through pkgs
  environment.systemPackages = with pkgs; [
    mcp-server-fetch
  ];
}

To generate a configuration file (like claude_desktop_config.json or .mcp.json) for your MCP clients, use the mkConfig function provided by the framework.

1. Create a config.nix file that imports the framework and calls mcp-servers-nix.lib.mkConfig.
2. Define your server configurations under the appropriate attribute set (e.g., programs.filesystem).
3. Build the configuration using nix-build and inspect the result file.

# config.nix
let
  pkgs = import <nixpkgs> { };
  mcp-servers-nix = import (fetchTarball
    "https://github.com/natsukium/mcp-servers-nix/archive/main.tar.gz") { inherit pkgs; };
in
  mcp-servers-nix.lib.mkConfig pkgs {
    programs.filesystem = {
      enable = true;
      args = [ "/path/to/allowed/directory" ];
    };
  }

Then run:

nix-build config.nix && cat result

The devenv module integrates with devenv's built-in claude.code.mcpServers option. Instead of generating .mcp.json via a shell hook, it outputs through devenv's native Claude Code support.

Key features:

• Declarative interface: Uses the same programs.<name>.enable pattern.
• Native devenv integration: Outputs through claude.code.mcpServers.
• Credential wrapping: envFile and passwordCommand work naturally as they produce Nix store paths.

Example devenv.yaml:

inputs:
  mcp-servers-nix:
    url: github:natsukium/mcp-servers-nix

Example devenv.nix:

{ inputs, pkgs, ... }: 
{
  imports = [ inputs.mcp-servers-nix.devenvModules.default ];

  claude.code.enable = true;

  mcp-servers.programs = {
    filesystem = {
      enable = true;
      args = [ "." ];
    };
    playwright.enable = true;
    context7.enable = true;
  };
}

For Flake-based setups, define your inputs in flake.nix and use mcp-servers-nix.lib.mkConfig within your outputs. This allows you to pin specific versions of nixpkgs and mcp-servers-nix.

Example flake.nix:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    mcp-servers-nix.url = "github:natsukium/mcp-servers-nix";
  };

  outputs = 
    {
      self,
      nixpkgs,
      mcp-servers-nix,
    }: 
    {
      packages.x86_64-linux.default = 
        let
          pkgs = import nixpkgs { system = "x86_64-linux"; };
        in
        mcp-servers-nix.lib.mkConfig pkgs {
          programs = {
            filesystem = {
              enable = true;
              args = [ "/path/to/allowed/directory" ];
            };
            fetch.enable = true;
          };
        };
    };
}

Build the configuration using:

nix build