A nix flake for configuring Model Context Protocol (MCP) servers across supported AI assistant clients
Documentation
Nix MCP Servers
A Nix flake for declaratively configuring MCP (Model Context Protocol) servers for clients like Claude and Cursor.
Features
- Declarative configuration of MCP servers
- Support for multiple clients (Claude, Cursor)
- Support for multiple server types (filesystem, github)
- Cross-platform support (NixOS, Darwin)
- Uses Home Manager for integration with your existing Nix configuration
How it Works
This flake provides Home Manager modules that generate MCP server configuration files for different clients. When you enable a server for a client, the necessary configuration is generated and placed in the appropriate location for that client.
Supported Servers
- Filesystem: Provides filesystem access to AI models
- GitHub: Provides GitHub access to AI models
Supported Clients
- Claude: Anthropic's Claude AI assistant
- Cursor: The Cursor code editor
Usage
Basic Usage
Add this flake to your home-manager configuration:
{
inputs = {
# ... your other inputs
nix-mcp-servers.url = "github:yourusername/nix-mcp-servers";
};
outputs = { nixpkgs, home-manager, nix-mcp-servers, ... }: {
homeConfigurations."yourusername" = home-manager.lib.homeManagerConfiguration {
# ... your other configuration
modules = [
nix-mcp-servers.homeManagerModules.default
# Your configuration
{
nix-mcp-servers = {
# Enable configuration generation
clients.generateConfigs = true;
# Configure Cursor client
clients.cursor = {
enable = true;
# Enable filesystem server for Cursor
filesystem = {
enable = true;
paths = [
"/Users/yourusername/projects"
"/Users/yourusername/Documents"
];
};
# Enable GitHub server for Cursor
github = {
enable = true;
token = "your-github-token";
};
};
# Configure Claude client
clients.claude = {
enable = true;
# Only enable filesystem for Claude
filesystem = {
enable = true;
paths = [
"/Users/yourusername/projects"
];
};
# Don't enable GitHub for Claude
github.enable = false;
};
};
}
];
};
};
}Custom Configuration Paths
You can customize the configuration paths for each client:
{
nix-mcp-servers = {
# Override base config path
configPath = "/custom/path/to/mcp";
clients.cursor = {
enable = true;
# Override Cursor config path
configPath = "/custom/path/to/cursor/mcp/config.json";
# ...rest of the configuration
};
};
}Development
To contribute to this project:
1. Clone the repository
2. Make your changes
3. Test with nix flake check
4. Submit a PR
License
Project Overview
This Nix flake provides a unified configuration system for Model Control Protocol (MCP) servers across different platforms and package managers. The project:
- Manages MCP server configurations for AI applications
- Handles client-specific configuration formats and paths
- Works across NixOS, nix-darwin, and Home Manager
- Provides cross-platform compatibility between Linux and macOS
- Supports multiple server types with server-specific configuration options
Installation & Usage
For detailed usage examples, see our documentation:
Quick start:
NixOS
Add to your configuration.nix:
{
inputs.mcp-servers.url = "github:aloshy-ai/nix-mcp-servers";
outputs = { self, nixpkgs, mcp-servers, ... }: {
nixosConfigurations.hostname = nixpkgs.lib.nixosSystem {
# ...
modules = [
mcp-servers.nixosModules.default
{
services.mcp-servers = {
enable = true; # Enable the entire module
servers = {
filesystem = {
# command = "npx"; # Uses default
filesystem = {
# args = [ "-y" "@modelcontextprotocol/server-filesystem" ]; # Uses default
extraArgs = [ "/Users/username/Desktop" "/path/to/other/allowed/dir" ]; # REQUIRED
};
};
github = {
env = {
GITHUB_PERSONAL_ACCESS_TOKEN = "xxxxxxxxxxxxxxx"; # REQUIRED through assertion
};
};
};
clients = {
claude = {
enable = true; # Using standard Nix 'enable' flag
# clientType defaults to "claudeDesktop" based on name
servers = [ "filesystem" "github" ];
};
cursor = {
enable = true; # Enable Cursor configuration
servers = [ "filesystem" ]; # Only use filesystem server for Cursor
};
};
};
}
];
};
};
}Home Manager
Add to your home.nix:
{
imports = [
(builtins.fetchTarball "https://github.com/aloshy-ai/nix-mcp-servers/archive/main.tar.gz").nixosModules.home-manager
];
services.mcp-servers = {
enable = true; # Enable the entire module
servers = {
filesystem = {
# command = "npx"; # Uses default
filesystem = {
# args = [ "-y" "@modelcontextprotocol/server-filesystem" ]; # Uses default
extraArgs = [ "/Users/username/Desktop" "/path/to/other/allowed/dir" ]; # REQUIRED
};
};
github = {
env = {
GITHUB_PERSONAL_ACCESS_TOKEN = "xxxxxxxxxxxxxxx"; # REQUIRED through assertion
};
};
};
clients = {
claude = {
enable = true; # Using standard Nix 'enable' flag
# clientType defaults to "claudeDesktop" based on name
servers = [ "filesystem" "github" ];
};
cursor = {
enable = true; # Enable Cursor configuration
servers = [ "filesystem" ]; # Only use filesystem server for Cursor
};
};
};
}nix-darwin
Add to your darwin-configuration.nix:
{
imports = [
(builtins.fetchTarball "https://github.com/aloshy-ai/nix-mcp-servers/archive/main.tar.gz").darwinModules.default
];
services.mcp-servers = {
enable = true; # Enable the entire module
servers = {
filesystem = {
# command = "npx"; # Uses default
filesystem = {
# args = [ "-y" "@modelcontextprotocol/server-filesystem" ]; # Uses default
extraArgs = [ "/Users/username/Desktop" "/path/to/other/allowed/dir" ]; # REQUIRED
};
};
github = {
env = {
GITHUB_PERSONAL_ACCESS_TOKEN = "xxxxxxxxxxxxxxx"; # REQUIRED through assertion
};
};
};
clients = {
claude = {
enable = true; # Using standard Nix 'enable' flag
# clientType defaults to "claudeDesktop" based on name
servers = [ "filesystem" "github" ];
};
cursor = {
enable = true; # Enable Cursor configuration
servers = [ "filesystem" ]; # Only use filesystem server for Cursor
};
};
};
}CLI Tool
The package also provides a mcp-servers CLI tool to help configure your MCP servers:
nix run github:aloshy-ai/nix-mcp-serversTesting Your Setup
After configuring the MCP server, you can verify the configuration was applied correctly:
For NixOS and nix-darwin
# For NixOS
sudo nixos-rebuild test
# For nix-darwin
darwin-rebuild testFor Home Manager
home-manager switchThen check if the configuration file exists:
# For Claude Desktop on macOS
cat ~/Library/Application\ Support/Claude/mcp-config.json
# For Claude Desktop on Linux
cat ~/.config/claude-desktop/mcp-config.json
# For Cursor on macOS
cat ~/Library/Application\ Support/Cursor/mcp-config.json
# For Cursor on Linux
cat ~/.config/Cursor/mcp-config.jsonYou should see a JSON configuration with your configured server information.
Module Structure
This project uses a modular structure for handling configuration across different platforms:
- Common Options: Defines the core module options for servers and clients
- Platform Adapters: Implements platform-specific configuration for NixOS, Darwin, and Home Manager
- Library Functions: Provides helper functions for path handling, platform detection, and configuration generation
Project Structure
This project uses flake-parts for a modular structure:
modules/- NixOS, Darwin, and Home Manager modulescommon/- Shared module definitions and optionsnixos/- NixOS-specific implementationdarwin/- Darwin-specific implementationhome-manager/- Home Manager implementationlib/- Utility functions used by the modulesclients.nix- Client-specific configuration handlingservers.nix- Server configuration formattingplatforms.nix- Platform detection and path utilitiespaths.nix- Path manipulation functionsdocs/- Documentationexamples/- Usage examplesmodules/- Module documentation
Documentation
- Module Options - Detailed documentation of all available options
- Usage Examples - Examples for different platforms
- Troubleshooting - Solutions for common issues
You can also generate and view the options documentation directly with:
nix run github:aloshy-ai/nix-mcp-servers#view-docsGitHub Pages Documentation
This repository is configured to automatically build and deploy documentation to GitHub Pages. The documentation is generated from the docs package in the flake and deployed whenever changes are pushed to the main branch.
The deployment is handled by the peaceiris/actions-gh-pages action, which creates a gh-pages branch with the documentation. This approach doesn't require any manual configuration of the GitHub Pages environment.
The URL to the generated documentation will be displayed in the GitHub repository details once deployed.
Similar MCP
Based on tags & features
Trending MCP
Most active this week