Nu MCP

What nu-mcp does

nu-mcp connects MCP clients to Nushell. In its default mode, it exposes a run tool that accepts Nushell commands for execution. The command environment is stateless across requests: every invocation starts a separate Nushell process, so variables, aliases, definitions, and other process state are not retained.

The server can also load tool modules written as Nushell scripts. Modules live in directories with a mod.nu entry file, allowing teams to add focused MCP tools without changing the Rust server. The repository includes modules for Kubernetes, ArgoCD, Tmux, and Context7, along with additional individually installable tool packages such as weather and finance tools.

How it works

The server is implemented in Rust with the official rmcp SDK. Start it in core mode with nu-mcp, or provide a tools directory with --tools-dir. Extension mode loads only the selected modules; hybrid mode combines those modules with the run tool by adding --enable-nu.

Each execution is subject to a configurable timeout. MCP_NU_MCP_TIMEOUT sets the default in seconds, and individual calls can supply timeout_seconds to override that default. The documented default is 300 seconds.

Nushell processes inherit a kernel-enforced sandbox supplied by nono. On Linux this uses Landlock, while macOS uses Seatbelt. The current working directory is read-write accessible by default. Additional read-write or read-only locations can be granted through command-line options, and network access can be blocked explicitly.

Setup and configuration

Nix and Homebrew installation paths are supported. Nix can install the standalone package, individual tool collections, or the complete collection; the package can also be used as an overlay in another flake. On macOS or Linux, the Homebrew tap installs nu-mcp.

Useful command-line options include:

• --tools-dir or -t to select a directory of Nushell tool modules.
• --enable-nu or -e to expose command execution alongside extension tools.
• --add-path and --add-read-path to grant extra filesystem access.
• --block-network to deny network access to sandboxed commands.
• --bypass-protection to unblock a sensitive path.
• --allow-binary to permit a named external binary in the sandbox.

The current directory remains accessible regardless of additional path settings. A typical MCP configuration invokes the nu-mcp executable and passes the desired tool directory and path grants as arguments.

Tools and capabilities

• Execute arbitrary Nushell commands with the core run tool.
• Load custom MCP tools from modular Nushell script directories.
• Use Kubernetes tools covering kubectl and Helm operations, with a three-tier safety model.
• Manage ArgoCD applications and resources through its HTTP API module.
• Manage Tmux sessions and panes with command-execution support.
• Retrieve library documentation and examples through the Context7 module.
• Apply per-server or per-call execution timeouts.
• Restrict filesystem, network, and executable access through sandbox options.

Destructive operations are marked with warnings and require explicit user confirmation. Examples include deleting GitHub releases, deleting or force-changing Kubernetes resources, uninstalling Helm releases, and ArgoCD synchronization with pruning. Several modules also expose read-only, non-destructive, and destructive safety modes through environment variables.