STeLA MCP

A Python implementation of a Model Context Protocol server that provides secure access to local system operations via a standardized API interface.

STeLA (Simple Terminal Language Assistant) MCP is a lightweight server that provides secure access to local machine commands and file operations via a standardized API interface. It acts as a bridge between applications and your local system, implementing the Model Context Protocol (MCP) architecture.

Overview

STeLA MCP implements the Model Context Protocol (MCP) architecture to provide a secure, standardized way for applications to execute commands and perform file operations on a local machine. It serves as an intermediary layer that accepts requests through a well-defined API, executes operations in a controlled environment, and returns formatted results.

Features

Command Execution: Run shell commands on the local system with proper error handling
File Operations: Read, write, and manage files on the local system
Directory Visualization: Generate recursive tree views of file systems
Working Directory Support: Execute commands in specific directories
Robust Error Handling: Detailed error messages and validation
Comprehensive Output: Capture and return both stdout and stderr
Simple Integration: Standard I/O interface for easy integration with various clients
Multi-Directory Support: Configure multiple allowed directories for file operations
Security-First Design: Strict path validation and command execution controls
File Search: Search for files matching a pattern
File Edit: Make selective edits to a file
Type Safety: Strong type checking with Pydantic models for all tool inputs
Path Validation: Enhanced symlink and parent directory validation

Installation

Installing via Smithery

To install STeLA for Claude Desktop automatically via Smithery:

bash

npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claude

Prerequisites

Python 3.10 - 3.12
pip or uv package manager
Pydantic v2.x

Installation Steps

1. Clone the repository:

bash

git clone 
cd stela-mcp

2. Create and activate a virtual environment:

bash

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

bash

pip install -e .

Creating a Binary Distribution

To create a self-contained binary:

1. Install PyInstaller:

bash

pip install pyinstaller

2. Create the binary:

bash

pyinstaller --onefile src/stella_mcp//server.py --name stela-mcp

The binary will be created in the dist directory.

Configuration

STeLA MCP can be configured using environment variables:

Directory Access Control

ALLOWED_DIRS (Required): Comma-separated list of directories where file operations are allowed
Example: /home/user/project,/home/user/docs
Default: Current working directory if not specified
Note: All paths must be absolute

ALLOWED_DIR (Optional): Primary directory for command execution context
Example: /home/user/project
Default: First directory from ALLOWED_DIRS or current working directory
Note: This is separate from ALLOWED_DIRS and controls command execution context

Command Execution Security

ALLOWED_COMMANDS (Optional): Comma-separated list of allowed shell commands
Example: ls,cat,pwd,echo
Default: ls,cat,pwd,echo
Special value: all to allow any command (not recommended)

ALLOWED_FLAGS (Optional): Comma-separated list of allowed command flags
Example: -l,-a,-h,--help
Default: -l,-a,-h,--help
Special value: all to allow any flag (not recommended)

MAX_COMMAND_LENGTH (Optional): Maximum length of command strings
Example: 1024
Default: 1024
Note: Prevents command injection via overly long strings

COMMAND_TIMEOUT (Optional): Maximum execution time for commands in seconds
Example: 60
Default: 60
Note: Prevents hanging commands

Example Configuration

bash

# Directory access
export ALLOWED_DIRS="/home/user/project,/home/user/docs"
export ALLOWED_DIR="/home/user/project"

# Command execution
export ALLOWED_COMMANDS="ls,cat,pwd,echo"
export ALLOWED_FLAGS="-l,-a,-h,--help"
export MAX_COMMAND_LENGTH=1024
export COMMAND_TIMEOUT=60

Project Structure

code

stela-mcp/
├── src/
│   ├── stela_mcp/
│   │   ├── __init__.py
│   │   ├── shell.py        # Shell command execution
│   │   ├── filesystem.py   # File system operations
│   │   └── security.py     # Security configuration
│   └── server.py           # Main server implementation
├── pyproject.toml          # Project configuration
└── README.md

Usage

Starting the Server

Run the server using:

bash

uv run python -m src.stella_mcp.server

The server will start and listen for connections through standard I/O.

Using with Claude Desktop

To use STeLA MCP with Claude Desktop:

1. Option 1: Using Python directly

Start the server using:

bash

uv run python -m src.stela_mcp.server

In Claude Desktop:
Go to Settings
Under "Tools", click "Add Tool"
Select "MCP Server"
Enter the following configuration:
Name: STeLA MCP
Path: The absolute path to your Python executable (e.g., /home/username/.venv/bin/python)
Arguments: -m src.stela_mcp.server
Working Directory: The path to your STeLA MCP project directory

2. Option 2: Using the binary

Copy the binary from dist/stela-mcp to a location in your PATH
In Claude Desktop:
Go to Settings
Under "Tools", click "Add Tool"
Select "MCP Server"
Enter the following configuration:
Name: STeLA MCP
Path: The absolute path to the binary (e.g., /usr/local/bin/stela-mcp)
Arguments: (leave empty)
Working Directory: (leave empty)

3. Once configured, you can use STeLA MCP tools in your conversations with Claude. For example:

"Show me the contents of my home directory"
"Create a new file called 'test.txt' with some content"
"Run the command 'ls -la' in my current directory"

4. Claude will automatically use the appropriate tools based on your requests and display the results in the conversation.

Available Tools

Command Tools

##### execute_command

Executes shell commands on the local system.

Parameters:

command (string, required): The shell command to execute
working_dir (string, optional): Directory where the command should be executed

Returns:

On success: Command output (stdout)
On failure: Error message and any command output (stderr)

##### change_directory

Changes the current working directory.

Parameters:

path (string, required): Path to change to

Returns:

On success: Success message with new path
On failure: Error message

File System Tools

##### read_file

Reads the contents of a file.

Parameters:

path (string, required): Path to the file to read

Returns:

On success: File contents
On failure: Error message

##### read_multiple_files

Reads multiple files simultaneously.

Parameters:

paths (array, required): List of file paths to read

Returns:

On success: Combined contents of all files
On failure: Error message and partial results

##### write_file

Writes content to a file.

Parameters:

path (string, required): Path where the file will be written
content (string, required): Content to write to the file

Returns:

On success: Success message
On failure: Error message

##### edit_file

Makes selective edits to a file.

Parameters:

path (string, required): Path to the file to edit
edits (array, required): List of edit operations
Each edit contains oldText and newText
dryRun (boolean, optional): Preview changes without applying

Returns:

On success: Git-style diff of changes
On failure: Error message

##### list_directory

Lists contents of a directory.

Parameters:

path (string, required): Path for the directory to list

Returns:

On success: List of files and directories
On failure: Error message

##### create_directory

Creates a new directory.

Parameters:

path (string, required): Path for the directory to create

Returns:

On success: Success message
On failure: Error message

##### move_file

Moves or renames files and directories.

Parameters:

source (string, required): Source path of the file or directory to move
destination (string, required): Destination path where the file or directory will be moved to

Returns:

On success: Success message
On failure: Error message

##### search_files

Searches for files matching a pattern.

Parameters:

path (string, required): Starting path for the search
pattern (string, required): Search pattern to match file and directory names
excludePatterns (array, optional): List of glob patterns to exclude

Returns:

On success: List of matching files
On failure: Error message

##### directory_tree

Generates a recursive tree view of files and directories.

Parameters:

path (string, required): Path for the directory to generate tree from

Returns:

On success: JSON structure representing the directory tree
On failure: Error message

##### get_file_info

Retrieves detailed metadata about a file or directory.

Parameters:

path (string, required): Path to the file or directory

Returns:

On success: File/directory metadata
On failure: Error message

##### list_allowed_directories

Lists all directories the server is allowed to access.

Parameters:

None

Returns:

On success: List of allowed directories
On failure: Error message

##### show_security_rules

Shows current security configuration.

Parameters:

None

Returns:

On success: Security configuration details
On failure: Error message

Security Considerations

STeLA MCP provides direct access to execute commands and file operations on the local system. Consider the following security practices:

Run with appropriate permissions (avoid running as root/administrator)
Use in trusted environments only
Consider implementing additional authorization mechanisms for production use
Be cautious about which directories you allow command execution and file operations in
Implement path validation to prevent unauthorized access to system files
Use the most restrictive configuration possible for your use case
Regularly review and update allowed commands and directories
Validate symlinks to prevent access outside allowed directories
Ensure parent directory checks for file creation operations

Platform-Specific Security Notes

Linux/macOS

Run with a dedicated user with limited permissions
Consider using a chroot environment to restrict file system access
Use chmod to restrict executable permissions
Consider using SELinux/AppArmor for additional security

Windows

Run as a standard user, not an administrator
Consider using Windows Security features to restrict access
Use folder/file permissions to limit access to sensitive directories
Consider using Windows Defender Application Control

Development

Adding New Tools

To extend STeLA MCP with additional functionality, follow this pattern:

1. Define a Pydantic model for the tool's input parameters in server.py

2. Add a new method to the appropriate class in shell.py or filesystem.py

3. Register the tool in server.py using the @server.call_tool() decorator

4. Implement the tool handler with proper error handling and return types

Example:

python

from pydantic import BaseModel, Field

class MyToolInput(BaseModel):
    param1: str = Field(description="Description of param1")
    param2: int = Field(description="Description of param2")

@server.call_tool()
async def my_tool(request: Request[MyToolInput, str], arguments: MyToolInput) -> Dict[str, Any]:
    """Description of the tool."""
    try:
        # Tool implementation
        result = await do_something(arguments.param1, arguments.param2)
        return {"success": True, "result": result}
    except Exception as e:
        return {"error": str(e)}

License

Apache-2.0 License

Acknowledgements

Built with the MCP Python SDK

Stela Mcp

Documentation

STeLA MCP

Overview

Features

Installation

Installing via Smithery

Prerequisites

Installation Steps

Creating a Binary Distribution

Configuration

Directory Access Control

Command Execution Security

Example Configuration

Project Structure

Usage

Starting the Server

Using with Claude Desktop

Available Tools

Command Tools

File System Tools

Security Considerations

Platform-Specific Security Notes

Linux/macOS

Windows

Development

Adding New Tools

License

Acknowledgements

Similar MCP

Nebulablock Mcp Server

Chuk Mcp Linkedin

Pursuit Mcp

Hello Mcp

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Nebulablock Mcp Server

Chuk Mcp Linkedin

Pursuit Mcp

Hello Mcp

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare