Nash MCP Server

Nash MCP (a Model Context Protocol (MCP) server) enables seamless execution of commands, Python code, web content fetching, and reusable task management.

Requirements

• Python 3.11+
• Poetry package manager (recommended)

Installation

git clone https://github.com/nash-run/nash-mcp.git
cd nash-mcp
poetry install

Features

• Command Execution: Run shell commands with error handling
• Python Execution: Execute Python code with error handling
• Secure Credentials: Store and access API keys without exposing sensitive data to the LLM
• Web Content Access: Fetch and parse webpage content for analysis
• Task Repository: Save and organize reusable workflows and scripts

Tools

Execute Module

• execute_command: Run shell commands with proper error handling and output capture
• list_session_files: List all Python files in the current session (ALWAYS USE THIS FIRST before creating new files)
• get_file_content: Retrieve file contents for reviewing and editing existing code
• edit_python_file: Make targeted edits to existing Python files using exact string pattern matching (PREFERRED METHOD)
• execute_python: Execute Python code snippets with full access to installed packages (use only for new files)
• list_installed_packages: Get information about available Python packages

Web Interaction

• fetch_webpage: Retrieve and convert webpage content to readable text format

Secrets Management

• nash_secrets: Access stored API keys and credentials securely. Accessible via environment variables in scripts.

Task Management

• save_nash_task: Create reusable tasks with embedded scripts
• list_nash_tasks: View all available saved tasks
• run_nash_task: Retrieve and display a previously saved task
• execute_task_script: Run a specific script from a saved task
• view_task_details: See complete details of a task, including script code
• delete_nash_task: Remove tasks that are no longer needed

Running

This is the command to use for MCP config files

/path/to/this/repo/.venv/bin/mcp run /path/to/this/repo/src/nash_mcp/server.py

As an example, if you were to use this MCP with Claude Desktop, you would change your ~/Library/Application Support/Claude/claude_desktop_config.json to:

{
  "mcpServers": {
    "Nash": {
      "command": "/Users/john-nash/code/nash-mcp/.venv/bin/mcp",
      "args": ["run", "/Users/john-nash/code/nash-mcp/src/nash_mcp/server.py"]
    }
  }
}

Environment Variables

Nash MCP requires environment variables to specify all data file paths. Create a .env file in the root directory with the following variables:

# Required environment variables
NASH_SECRETS_PATH=/path/to/secrets.json
NASH_TASKS_PATH=/path/to/tasks.json
NASH_LOGS_PATH=/path/to/logs/directory
NASH_SESSIONS_PATH=/path/to/sessions/directory

There are no default values - all paths must be explicitly configured.

Session Management

The Nash MCP server creates a unique session directory for each server instance. This session directory stores:

• Python scripts executed during the session
• Backup files of edited scripts
• Error logs and exception information

This persistent storage enables powerful workflows:

1. Scripts are saved with descriptive names for easy reference
2. Previous scripts can be viewed and modified instead of rewritten
3. Errors are captured in companion files for debugging

Mandatory Workflow

⚠️ MANDATORY PRE-CODING CHECKLIST - COMPLETE BEFORE WRITING ANY CODE: ⚠️

1. Check available packages: list_installed_packages()
   - Know what libraries you can use
   - Avoid importing unavailable packages
   
2. Check available secrets: nash_secrets()
   - See what API keys and credentials are available
   - Don't write code requiring credentials you don't have
   
3. Check existing files: list_session_files()
   - See what code already exists
   - Avoid duplicating existing functionality
   
4. Review relevant file contents: get_file_content("filename.py")
   - Understand existing implementations
   - Decide whether to edit or create new

File Editing Best Practices

When working with Nash MCP, balance efficiency and context preservation:

1. Always check for existing files before creating new ones using list_session_files()
2. Prioritize editing with edit_python_file() for minor to moderate changes
3. Consider creating new files when:
   • It would be more token-efficient than explaining complex edits
   • You would need to replace almost the entire file
   • The task involves completely new functionality
   • Creating a new file would result in a cleaner, smaller response

The golden rule is to minimize token usage while maintaining context and code history.

This approach preserves script history, maintains context, and makes incremental development more efficient. The editing workflow follows this pattern:

1. First, check available resources → list_installed_packages() and nash_secrets()
2. List all existing files → list_session_files()
3. Check content of relevant files → get_file_content("file_name.py")
4. Make changes to existing file → edit_python_file("file_name.py", old_content, new_content)
5. Run the modified file → execute_python("", "file_name.py") (empty code string to run without modifying)
6. Only create new files when nothing similar exists → execute_python(new_code, "new_file.py")

Common Mistakes to Avoid

1. Creating a new file when a small edit would be more token-efficient
2. Making complex edits when creating a new file would be more token-efficient
3. Trying to use packages that aren't installed
4. Writing code that requires API keys you don't have
5. Rewriting functionality that already exists
6. Not considering token efficiency in your approach

Token Efficiency Guidelines

When deciding whether to edit or create a new file, consider which approach will use fewer tokens:

• Edit when: Changes are small to moderate, localized to specific sections, and easy to describe
• Create new when: Changes would replace most of the file, edits would be complex to explain, or a completely new approach is needed

Always aim to produce the smallest, most efficient output that accomplishes the task while maintaining clarity and context.

Security Considerations

• Commands and scripts run with the same permissions as the MCP server
• API keys and credentials are stored locally and loaded as environment variables
• Always review scripts before execution, especially when working with sensitive data

Development

Logs

Detailed timestamped logs of all operations and tool executions are emitted by the server. These logs are stored in the directory specified by the NASH_LOGS_PATH environment variable.

Testing

poetry run pytest

With coverage

poetry run pytest --cov=nash_mcp

License

MIT