nu-mcp
ck3mp3r/nu-mcp
Model Context Protocol (MCP) server built with Rust that exposes Nushell for command execution and provides an extensible system for creating modular MCP tools as Nushell scripts.
Instalação
npx convez-ai ck3mp3r/nu-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
nu-mcp: Model Context Protocol (MCP) Server for Nushell
This project exposes Nushell as an MCP server using the official Rust SDK (rmcp).
Features
- Exposes a tool to run arbitrary Nushell commands via MCP
- Persistent shell - State (environment variables, aliases, definitions) is preserved between commands
- Shell reset - Use
reset: trueto get a clean shell when needed - Configurable timeout support - Set global defaults via
MCP_NU_MCP_TIMEOUTor per-call withtimeout_secondsparameter - Extensible tool system via Nushell scripts in modular directories
- Uses the official Model Context Protocol Rust SDK
- Security sandbox with intelligent path validation and caching
- Catalog of useful MCP tools for Kubernetes, ArgoCD, Tmux, Context7 and more
Quick Start
Core Mode (Default)
nu-mcp
Provides the run tool for executing Nushell commands in a persistent shell. Environment variables, aliases, and definitions are preserved between calls. Use reset: true to get a clean environment when needed.
Extension Mode
nu-mcp --tools-dir=./tools
Load tools from the included catalog or your custom tool modules. Each tool is a directory with a mod.nu entry file.
Hybrid Mode
nu-mcp --tools-dir=./tools --enable-run-nu
Combine both core command execution and extension tools.
Available Tools
The tools/ directory contains a growing catalog of useful MCP tools:
- Kubernetes (
tools/k8s/) - Complete kubectl/Helm interface with 22 tools and three-tier safety model - ArgoCD (
tools/argocd/) - ArgoCD application and resource management via HTTP API - Tmux (
tools/tmux/) - Tmux session and pane management with intelligent command execution - Context7 (
tools/c67/) - Up-to-date library documentation and code examples from Context7
Configuration
Command Line Options
--tools-dir=PATH- Directory containing tool modules--enable-run-nu- Enable generic command execution alongside tools--add-path=PATH- Add additional accessible paths (current directory always included)
Environment Variables
MCP_NU_MCP_TIMEOUT- Default timeout in seconds for tool execution (default: 300)MCP_PTY_TRACE- Set to1to enable PTY trace logging to/tmp/pty_trace.log(persistent mode only, for debugging)
Example MCP Configuration
nu-mcp:
command: "nu-mcp"
args: ["--tools-dir=./tools", "--add-path=/tmp", "--add-path=/nix/store"]
env:
MCP_NU_MCP_TIMEOUT: "120" # 2 minute timeout
Note: Current working directory is always accessible. Use --add-path to grant access to additional paths.
Path Validation
The security sandbox intelligently handles path-like strings that aren't filesystem paths:
# API endpoints work without escaping sandbox
kubectl get --raw /metrics | from json
gh api /repos/owner/repo/contents/file.yml
# Path-like arguments in commands work correctly
echo "API endpoint: /api/v1/pods"
The sandbox uses a two-tier system (safe patterns + runtime caching) to eliminate false positives while maintaining security.
For detailed configuration options and tool development, see the documentation.
Safety and Destructive Operations
IMPORTANT: All destructive MCP tools require explicit user confirmation before execution.
Destructive tools (delete, cleanup, force operations, etc.) include explicit warnings in their descriptions:
DESTRUCTIVE OPERATION - ALWAYS ASK USER FOR EXPLICIT CONFIRMATION BEFORE EXECUTING.
[specific consequence]. This operation cannot be undone.
Tools with destructive capabilities:
- gh:
delete_release(deletes release + binaries),close_prwithdelete_branch - k8s:
kube_delete,helm_uninstall,kube_cleanup,kube_scale(to 0) - ArgoCD:
delete_application,sync_applicationwithprune: true
LLM Agents: These warnings instruct LLMs to ALWAYS ask for user permission before executing destructive operations. Never execute these tools without explicit user confirmation.
Safety Modes: Many tools implement safety modes (readonly/non-destructive/destructive) via environment variables. See individual tool READMEs for details.
Installation
Via Nix
As a Nix profile (standalone usage)
You can install this flake as a Nix profile:
nix profile install github:ck3mp3r/nu-mcp
Or, if you have a local checkout:
nix profile install path:/absolute/path/to/nu-mcp
Installing Tools
Tools are available as individual packages or as a complete collection:
Individual Tools
# Kubernetes tool only
nix profile install github:ck3mp3r/nu-mcp#k8s-mcp-tools
# ArgoCD tool only
nix profile install github:ck3mp3r/nu-mcp#argocd-mcp-tools
# Weather tool only
nix profile install github:ck3mp3r/nu-mcp#weather-mcp-tools
# Finance tool only
nix profile install github:ck3mp3r/nu-mcp#finance-mcp-tools
# Tmux tool only
nix profile install github:ck3mp3r/nu-mcp#tmux-mcp-tools
# Context7 (c67) tool only
nix profile install github:ck3mp3r/nu-mcp#c67-mcp-tools
Complete Tool Collection
# All available tools
nix profile install github:ck3mp3r/nu-mcp#mcp-tools
Tools are installed to ~/.nix-profile/share/nushell/mcp-tools/.
As an overlay in your own flake
Add this flake as an input and overlay in your flake.nix:
{
inputs.nu-mcp.url = "github:ck3mp3r/nu-mcp";
# ...
outputs = { self, nixpkgs, nu-mcp, ... }:
let
overlays = [ nu-mcp.overlays.default ];
pkgs = import nixpkgs { inherit system overlays; };
in {
# Now pkgs.nu-mcp is available
packages.x86_64-linux.nu-mcp = pkgs.nu-mcp;
};
}
You can now use pkgs.nu-mcp in your own packages, devShells, or CI.
Via Homebrew (macOS and Linux)
Install from the tap:
brew tap ck3mp3r/nu-mcp https://github.com/ck3mp3r/nu-mcp
brew install nu-mcp
Development
- See modelcontextprotocol/rust-sdk for SDK details and advanced usage.
- The code is modular and fully async.
- Tests are in
tests/filter.rs.
Creating Tools
Tools are modular Nushell scripts organized in directories with a mod.nu entry file. See docs/tool-development.md for detailed guidance.
Security
Commands execute within a configurable directory sandbox. See docs/security.md for detailed security considerations.
Documentation
- Configuration Guide - Setup and configuration options
- Tool Development - Creating modular tools
- Testing - Testing and debugging tools
- Architecture - Additional technical documentation