Local Utilities MCP Server

# 🛠️ 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. [](https://www.python.org/downloads/) [](https://pypi.org/project/fastmcp/) [](https://opensource.org/licenses/MIT) ## 🌟 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:** ```bash git clone https://github.com/aiforhumans/local-utils-mcp.git cd local-utils-mcp ``` 2. **Create and activate a virtual environment:** ```bash python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate ``` 3. **Install dependencies:** ```bash pip install -r requirements.txt ``` ### Running the Server **Start the MCP server:** ```bash 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: ```json { "mcpServers": { "local-utils": { "command": "python", "args": ["path/to/your/server.py"], "env": {} } } } ``` ### Claude Desktop Integration Add to your Claude Desktop configuration: ```json { "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: ```bash 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: ```python @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 [LICENSE](LICENSE) file for details. ## 🔗 Related Projects - [FastMCP](https://github.com/jlowin/fastmcp) - The FastMCP framework used to build this server - [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation - [LM Studio](https://lmstudio.ai/) - 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**