local-utils-mcp

Name: local-utils-mcp
Availability: InStock
Author: aiforhumans

a comprehensive MCP server providing utility tools for text processing, file operations, and system tasks

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

🛠️ Local Utilities MCP Server

A comprehensive Model Context Protocol (MCP) server built with FastMCP that provides essential utility tools for text processing, file operations, system tasks, and more.

🌟 Features

🌡️ Temperature Conversion

Convert between Celsius and Fahrenheit
High precision calculations with 2 decimal places

📁 File Operations

Read text files with full content display
Write content to files with automatic directory creation
List directory contents with file sizes and icons

🔐 Security & Hashing

Calculate MD5, SHA1, SHA256 hashes
Hash text strings or entire file contents
Base64 encoding and decoding

📊 Text Analysis

Count words, characters, and lines
Calculate detailed text statistics
Average words per line and characters per word

🕒 Date & Time

Get current date and time information
Custom formatting with Python strftime
Detailed breakdown (year, month, day, weekday, etc.)

🔑 Password Generation

Generate secure passwords with customizable options
Control length and character sets
Include/exclude uppercase, lowercase, numbers, symbols

🚀 Quick Start

Prerequisites

Python 3.8 or higher
Compatible MCP client (LM Studio, Claude Desktop, etc.)

Installation

Clone the repository:

git clone https://github.com/aiforhumans/local-utils-mcp.git
cd local-utils-mcp

Create and activate a virtual environment:

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Running the Server

Start the MCP server:

python server.py

The server runs on stdio transport by default, which is compatible with most MCP clients.

🔧 Configuration

LM Studio Integration

Add this configuration to your LM Studio mcp.json file:

{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"],
      "env": {}
    }
  }
}

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "local-utils": {
      "command": "python",
      "args": ["path/to/your/server.py"]
    }
  }
}

📖 API Reference

Available Tools

`convert_temp(value: float, unit: str)`

Convert temperature between Celsius and Fahrenheit.

Parameters:

value: Temperature value to convert
unit: "C" for Celsius to Fahrenheit, "F" for Fahrenheit to Celsius

Example:

convert_temp(25, "C") → "77.00 °F"
convert_temp(77, "F") → "25.00 °C"

`read_file(file_path: str)`

Read and return the contents of a text file.

Parameters:

file_path: Absolute or relative path to the file

Returns: File contents with path information

`write_file(file_path: str, content: str)`

Write content to a text file with automatic directory creation.

Parameters:

file_path: Path where to write the file
content: Text content to write

`list_directory(directory_path: str = ".")`

List contents of a directory with file sizes.

Parameters:

directory_path: Path to directory (defaults to current directory)

Returns: Formatted list with file/folder icons and sizes

`calculate_hash(text_or_path: str, hash_type: str = "sha256", is_file: bool = False)`

Calculate cryptographic hash of text or file content.

Parameters:

text_or_path: Text string or file path to hash
hash_type: "md5", "sha1", or "sha256" (default)
is_file: Set to true when hashing a file

`base64_encode_decode(text: str, operation: str = "encode")`

Encode or decode text using Base64.

Parameters:

text: Text to encode/decode
operation: "encode" or "decode"

`get_datetime_info(format_string: str = "%Y-%m-%d %H:%M:%S")`

Get comprehensive current date and time information.

Parameters:

format_string: Python strftime format string for custom formatting

`text_stats(text: str)`

Calculate detailed statistics for the given text.

Parameters:

text: Text to analyze

Returns: Lines, words, characters, and averages

`generate_password(length: int = 12, include_uppercase: bool = True, include_lowercase: bool = True, include_numbers: bool = True, include_symbols: bool = False)`

Generate a secure random password.

Parameters:

length: Password length (default: 12)
include_uppercase: Include A-Z (default: true)
include_lowercase: Include a-z (default: true)
include_numbers: Include 0-9 (default: true)
include_symbols: Include special characters (default: false)

🧪 Testing

Run the test suite to verify functionality:

python test.py

This will test all core functions and verify the server can be imported correctly.

🔨 Development

Adding New Tools

To extend the server with additional tools:

Create a new function with the @mcp.tool() decorator:

@mcp.tool(
    description="Your tool description here"
)
async def your_new_tool(param1: str, param2: int = 10) -> str:
    """
    Your tool implementation.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2 with default value
    
    Returns:
        String result of the tool operation
    """
    try:
        # Your tool logic here
        result = f"Processed {param1} with value {param2}"
        return result
    except Exception as e:
        return f"Error: {str(e)}"

Add proper error handling and meaningful return messages
Update the README with documentation for your new tool
Test your tool to ensure it works correctly

Project Structure

local-utils-mcp/
├── server.py              # Main MCP server
├── requirements.txt       # Python dependencies  
├── README.md             # This file
├── .gitignore           # Git ignore rules
├── test.py              # Test suite
└── .venv/               # Virtual environment (not in git)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.