convez.ai
MCP Server
ck3mp3r

nu-mcp

ck3mp3r/nu-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

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-mcp

1 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

Estrelas
9
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v0.10.0
Issues abertas
1
Contribuidores
3

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: true to get a clean shell when needed
  • Configurable timeout support - Set global defaults via MCP_NU_MCP_TIMEOUT or per-call with timeout_seconds parameter
  • 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 to 1 to 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_pr with delete_branch
  • k8s: kube_delete, helm_uninstall, kube_cleanup, kube_scale (to 0)
  • ArgoCD: delete_application, sync_application with prune: 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

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

Ver o original no GitHub

Bom para

Relacionados