aiforhumans/local-utils-mcp

🛠️ 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

1. Clone the repository:

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

2. Create and activate a virtual environment:

   python -m venv .venv
   
   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate
   

3. 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:

1. 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)}"

2. Add proper error handling and meaningful return messages
3. Update the README with documentation for your new tool
4. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📋 Requirements

• Python 3.8+
• FastMCP 2.9.0+
• MCP 1.9.4+

See requirements.txt for complete dependency list.

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Related Projects

• FastMCP - The FastMCP framework used to build this server
• Model Context Protocol - Official MCP documentation
• LM Studio - Popular MCP client for local AI models

⭐ Support

If you find this project helpful, please consider giving it a star on GitHub!

Made with ❤️ for the MCP community