mcp-servers-nix

一个基于 Nix 的配置框架，用于模型控制协议 (MCP) 服务器，并提供即用型软件包。

概述

本仓库提供 MCP 服务器软件包和一个用于配置和部署 MCP 服务器的 Nix 框架。它提供了一种模块化的方法，可以使用一致的接口来配置各种 MCP 服务器。

特性

• 模块化配置：定义和组合多个 MCP 服务器配置
• 可复现的构建：利用 Nix 实现可复现和声明式的服务器设置
• 预配置模块：适用于流行 MCP 服务器类型的即用型配置
• 安全至上：通过 envFile 和 passwordCommand 更好地处理凭据和敏感信息，并锁定服务器版本

快速上手

无需安装的快速使用

您可以直接运行 MCP 服务器软件包，而无需安装它们：

# 使用 nix-shell
nix-shell -p "(import (builtins.fetchTarball \"https://github.com/natsukium/mcp-servers-nix/archive/main.tar.gz\") {}).mcp-server-fetch" --run mcp-server-fetch

# 使用 flakes
nix run github:natsukium/mcp-servers-nix#mcp-server-fetch

安装软件包

有几种方法可以安装和使用此仓库提供的软件包：

直接安装软件包

您可以直接安装单个 MCP 服务器软件包：

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

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

使用 Overlays

您可以使用提供的 overlays 将所有 MCP 服务器软件包添加到您的 pkgs 中：

# 在您的 configuration.nix 或 home.nix 中
{
  nixpkgs.overlays = [
    # 经典方式
    (import (builtins.fetchTarball "https://github.com/natsukium/mcp-servers-nix/archive/main.tar.gz")).overlays.default
    # 或者使用 flakes
    # mcp-servers-nix.overlays.default 
  ];

  # 然后您可以通过 `pkgs` 安装软件包
  environment.systemPackages = with pkgs; [
    mcp-server-fetch
  ];
}

模块使用

不使用 flakes 的经典方法

1. 创建一个配置文件：

# config.nix
let
  pkgs = import (builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/refs/heads/nixos-unstable.tar.gz") { };
  mcp-servers = import (builtins.fetchTarball "https://github.com/natsukium/mcp-servers-nix/archive/refs/heads/main.tar.gz") { inherit pkgs; };
in
mcp-servers.lib.mkConfig pkgs {
  programs = {
    filesystem.enable = true;
    fetch.enable = true;
    # 根据需要添加更多模块
  };
}

2. 构建您的配置：

nix-build config.nix

// result
{
  "mcpServers": {
    "fetch": {
      "args": [],
      "command": "/nix/store/dbx03yjf6h14h5rvdppzj2fyhfjpx99g-mcp-server-fetch-2025.3.28/bin/mcp-server-fetch",
      "env": {}
    },
    "filesystem": {
      "args": [],
      "command": "/nix/store/i0v4ynavmz3iilr27c7iqg4dc3xxnygb-mcp-server-filesystem-2025.3.28/bin/mcp-server-filesystem",
      "env": {}
    }
  }
}

使用 npins

npins 是一个简单的依赖锁定工具，允许您保证可复现的构建，而无需使用 flakes：

1. 在您的项目中初始化 npins：

npins init

2. 将 mcp-servers-nix 添加为依赖项：

npins add github natsukium mcp-servers-nix -b main

3. 使用锁定的版本创建您的配置：

# config.nix
let
  sources = import ./npins;
  pkgs = import sources.nixpkgs {};
  mcp-servers = import sources.mcp-servers-nix {};
in
mcp-servers.lib.mkConfig pkgs {
  programs = {
    filesystem.enable = true;
    fetch.enable = true;
    # 根据需要添加更多模块
  };
}

4. 构建您的配置：

nix-build config.nix

使用 Flakes

1. 创建一个配置文件：

# 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;
            fetch.enable = true;
          };
        };
    };
}

2. 构建您的配置：

nix build

示例

查看 examples 目录以获取完整的配置示例：

• claude-desktop.nix: Claude Desktop 的基本配置
• vscode.nix: VS Code 集成设置
• librechat.nix: LibreChat 集成配置

真实世界示例

查看 GitHub 搜索结果 以了解其他人如何在他们的项目中使用 mcp-servers-nix。

配置选项

每个模块都提供特定的配置选项，但所有模块都有一些通用的选项：

全局选项

• format：配置文件格式（json 或 yaml，默认值：json）
• flavor：配置文件类型（claude 或 vscode，默认值：claude）
• fileName：配置文件名（默认值：claude_desktop_config.json）
• settings：将与生成的配置合并的自定义设置

通用模块选项

每个启用的模块（使用 programs.<module>.enable = true;）提供以下选项：

• package：用于此模块的软件包
• type：服务器连接类型（sse 或 stdio，默认值：null）
• args：传递给命令的参数数组（默认值：[]）
• env：服务器的环境变量（默认值：{}）
• url：用于 "sse" 连接的服务器 URL（默认值：null）
• envFile：从中加载其他环境变量的 .env 文件的路径（默认值：null）
• passwordCommand：执行以检索格式为 "KEY=VALUE" 的密钥的命令，该密钥将导出为环境变量，用于与密码管理器集成（默认值：null）

安全提示

出于安全原因，请勿在 env 属性中硬编码身份验证凭据。/nix/store 中的所有文件都可以被任何有权访问存储的人读取。始终使用 envFile 或 passwordCommand 代替。

当设置 envFile 或 passwordCommand 时，系统会自动包装软件包，这允许安全地检索凭据，而不会在 Nix 存储中暴露它们。

可用模块

该框架包括以下 MCP 服务器的模块：

• aws-kb-retrieval
• brave-search
• everart
• everything
• fetch
• filesystem
• gdrive
• git
• github
• gitlab
• google-maps
• memory
• playwright
• postgres
• puppeteer
• redis
• sentry
• sequential-thinking
• slack
• sqlite
• time

添加自定义服务器

您可以通过直接在 settings.servers 部分中配置它们来添加自己的自定义 MCP 服务器。这对于集成未包含在此仓库中的 MCP 服务器非常有用。

示例：添加 Obsidian 集成

以下是如何添加 mcp-obsidian 服务器以与 Obsidian 集成的示例：

mcp-servers.lib.mkConfig pkgs {
  format = "yaml";
  fileName = "config.yaml";
  
  # 配置内置模块
  programs = {
    filesystem = {
      enable = true;
      args = [ "/path/to/files" ];
    };
  };
  
  # 添加自定义 MCP 服务器
  settings.servers = {
    mcp-obsidian = {
      command = "${pkgs.lib.getExe' pkgs.nodejs "npx"}";
      args = [
        "-y"
        "mcp-obsidian"
        "/path/to/obsidian/vault"
      ];
    };
  };
}

这种方法允许您将任何 MCP 兼容的服务器集成到您的配置中，而无需创建专用模块。

有关模块特定的配置选项，请参阅 modules/ 目录中的各个模块源文件。

添加新的 MCP 服务器

您可以通过添加软件包定义和模块配置来使用新的 MCP 服务器扩展 mcp-servers-nix。

软件包结构

1. 官方软件包位于 pkgs/official/ 中
2. 参考实现位于 pkgs/reference/ 中
3. 社区实现位于 pkgs/community/ 中

示例：添加新的官方服务器软件包

在 pkgs/official/new-mcp-server/default.nix 中创建一个新的软件包定义：

{
  lib,
  fetchFromGitHub,
  buildNpmPackage,
}:

buildNpmPackage rec {
  pname = "new-mcp-server";
  version = "0.1.0";

  src = fetchFromGitHub {
    owner = "new-mcp-server";
    repo = "new-mcp-server";
    tag = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
  };

  npmDepsHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";

  meta = {
    description = "New MCP server";
    homepage = "https://github.com/new-mcp-server/new-mcp-server";
    license = lib.licenses.asl20;
    maintainers = with lib.maintainers; [ username ];
    mainProgram = "new-mcp-server";
  };
}

然后在 pkgs/default.nix 中注册它：

{
  # ... 现有软件包 ...
  
  # 新服务器
  new-mcp-server = pkgs.callPackage ./official/new-mcp-server { };
}

模块配置

在 modules/new-mcp-server.nix 中创建一个新模块：

{ mkServerModule, ... }:
{
  imports = [
    (mkServerModule {
      name = "new-mcp-server";
      packageName = "new-mcp-server";
    })
  ];
}

mkServerModule 函数 提供了使用一致的选项创建模块配置的框架。有关可用功能的更多详细信息，请参阅其实现。

添加自定义模块选项

除了 mkServerModule 提供的通用选项之外，您还可以为模块定义自定义选项。这允许您公开服务器特定的配置，这些配置可以由用户设置。

{ config, pkgs, lib, mkServerModule, ... }:
let
  cfg = config.programs.new-mcp-server;
in
{
  imports = [
    (mkServerModule {
      name = "new-mcp-server";
      packageName = "new-mcp-server";
    })
  ];

  # 为此模块定义自定义选项
  options.programs.new-mcp-server = {
    customOption = lib.mkOption {
      type = lib.types.str;
      default = "default-value";
      description = ''
        自定义选项的描述
      '';
    };
    
    binaryPath = lib.mkOption {
      type = lib.types.path;
      default = lib.getExe pkgs.some-package;
      description = ''
        服务器所需的二进制文件的路径
      '';
    };
  };

  # 使用自定义选项来修改服务器配置
  config.settings.servers = lib.mkIf cfg.enable {
    new-mcp-server = {
      args = [
        "--option"
        cfg.customOption
        "--binary-path"
        cfg.binaryPath
      ];
    };
  };
}

对于更复杂的服务器，您可以检查 pkgs/ 和 modules/ 目录中的现有实现作为参考。

许可证

本项目采用 Apache License 2.0 许可证 - 有关详细信息，请参阅 LICENSE 文件。