breezi

rajuX75/breezi

3.2

If you are the rightful owner of breezi and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A production-ready Model Context Protocol (MCP) server that provides programmatic control over Windows OS operations through Google's Gemini API.

Tools
4
Resources
0
Prompts
0

Windows MCP Server with Gemini API

A production-ready Model Context Protocol (MCP) server that provides programmatic control over Windows OS operations through Google's Gemini API. Built with enterprise-grade security, comprehensive logging, and modular architecture.

🌟 Features

  • 🤖 Gemini AI Integration: Full integration with Google's Gemini API for intelligent task execution
  • 📁 File Management: Safe file and folder operations with path validation
  • 💻 System Information: Comprehensive Windows system monitoring
  • 🚀 Application Control: Launch and manage Windows applications
  • ⚙️ Process Management: Monitor and control running processes
  • 🔒 Enterprise Security: Path whitelisting, input validation, audit logging
  • 📊 Comprehensive Logging: Rotating logs with debug and audit trails
  • 🔌 Modular Architecture: Easy-to-extend tool system
  • ⚡ Performance: Async operations, caching, rate limiting

📋 Prerequisites

  • Windows 10/11 (tested on Windows 10+)
  • Python 3.8+
  • Google Gemini API Key (Get one here)

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/windows-mcp-server.git
cd windows-mcp-server

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

Copy the example environment file and add your API key:

copy .env.example .env

Edit .env and add your Gemini API key:

GEMINI_API_KEY=your_api_key_here

4. Configure Security Settings

Edit .env to set allowed paths for file operations:

ALLOWED_PATH_1=C:\Users\YourUsername\Documents
ALLOWED_PATH_2=C:\Projects

🎯 Quick Start

Start the Server

python main.py

You should see:

============================================================
Starting Windows MCP Server with Gemini API
============================================================
✓ Gemini API connection established
✓ Loaded 4 tools: file_management, system_info, app_launcher, process_manager
✓ MCP Server initialized successfully
============================================================
Server is ready to accept requests
Press Ctrl+C to stop
============================================================

Example Usage

The server is now running and ready to receive MCP protocol requests or interact with Gemini AI.

🛠️ Available Tools

1. File Management (file_management)

Manage files and folders with security controls.

Operations:

  • list: List directory contents with filtering
  • create_folder: Create new directories
  • delete: Remove files or folders
  • copy: Copy files or folders
  • move: Move files or folders
  • info: Get detailed file/folder information

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "file_management",
    "arguments": {
      "operation": "list",
      "path": "C:\\Users\\YourName\\Documents",
      "recursive": false
    }
  }
}

2. System Information (system_info)

Get comprehensive Windows system information.

Info Types:

  • all: All system information
  • os: Operating system details
  • cpu: Processor information and usage
  • memory: RAM and swap usage
  • disk: Disk space and I/O stats
  • network: Network interfaces and stats
  • battery: Battery status (laptops)

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "system_info",
    "arguments": {
      "info_type": "cpu"
    }
  }
}

3. Application Launcher (app_launcher)

Launch and manage Windows applications.

Operations:

  • launch: Start an application
  • open_file: Open file with default app
  • run_command: Execute a command

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "app_launcher",
    "arguments": {
      "operation": "launch",
      "application": "notepad.exe",
      "arguments": ["C:\\temp\\file.txt"]
    }
  }
}

4. Process Manager (process_manager)

Monitor and manage running processes.

Operations:

  • list: List all running processes
  • details: Get detailed process information
  • terminate: Stop a process
  • exists: Check if process is running

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "process_manager",
    "arguments": {
      "operation": "list",
      "sort_by": "cpu",
      "limit": 10
    }
  }
}

🔧 Configuration

All configuration is managed through environment variables in .env:

Gemini API Settings

GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-1.5-pro # Models like gemini-2.5-flash, gemini-2.5-pro are also supported
GEMINI_TEMPERATURE=0.7
GEMINI_MAX_TOKENS=8192

Security Settings

ALLOWED_PATH_1=C:\Users\YourName\Documents
ALLOWED_PATH_2=C:\Projects
MAX_FILE_SIZE_MB=100
ALLOWED_APPLICATIONS=notepad.exe,calc.exe,mspaint.exe

Performance Settings

REQUEST_TIMEOUT=30
ENABLE_CACHING=true
CACHE_TTL=300
MAX_REQUESTS_PER_MINUTE=60

Logging Settings

LOG_LEVEL=INFO
LOG_FILE=logs/mcp_server.log
AUDIT_LOG_FILE=logs/audit.log

🔌 Adding Custom Tools

Creating a new tool is easy! Follow these steps:

1. Create a New Tool File

Create tools/my_new_tool.py:

from tools.base_tool import BaseTool
from typing import Dict, Any, List

class MyNewTool(BaseTool):
    def get_name(self) -> str:
        return "my_tool"

    def get_description(self) -> str:
        return "Description of what this tool does"

    def get_parameters(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }

    def validate_input(self, **kwargs) -> bool:
        # Validate inputs
        return True

    def get_required_permissions(self) -> List[str]:
        return ["permission_name"]

    async def execute(self, param1: str, **kwargs) -> Dict[str, Any]:
        # Implement your tool logic
        result = f"Processed: {param1}"
        return self._success_response({"result": result})

2. Restart the Server

The tool will be automatically discovered and loaded!

python main.py

🔒 Security Features

Path Security

  • Whitelist-based: Only allowed paths are accessible
  • Blacklist protection: System directories are blocked
  • Path traversal prevention: "../" attacks are blocked
  • Validation: All paths are validated and sanitized

Input Validation

  • Schema validation: All inputs validated against JSON schemas
  • Sanitization: Dangerous characters removed
  • Size limits: File size and response size limits
  • Type checking: Strong type validation

Audit Logging

All security-sensitive operations are logged to logs/audit.log:

  • File deletions
  • Process terminations
  • Security violations
  • Failed access attempts

Application Whitelisting

Configure allowed applications in .env:

ALLOWED_APPLICATIONS=notepad.exe,calc.exe,mspaint.exe,cmd.exe

📊 Monitoring & Logging

Log Files

  • Main Log: logs/mcp_server.log - All server operations
  • Audit Log: logs/audit.log - Security-sensitive events

Health Check

Check server health:

{
  "method": "health",
  "params": {}
}

Response includes:

  • Server status
  • Uptime
  • Request count
  • Error rate
  • Tools loaded
  • Gemini connection status

🐛 Troubleshooting

API Key Issues

Configuration Error: GEMINI_API_KEY is not set

Solution: Add your API key to .env

Permission Errors

SecurityError: Path not in allowed directories

Solution: Add the path to ALLOWED_PATH_N in .env

Import Errors

ModuleNotFoundError: No module named 'google.generativeai'

Solution: Run pip install -r requirements.txt

Process Access Denied

Access denied. Elevated privileges required

Solution: Run as Administrator for system process access

.env File Parsing Errors

python-dotenv could not parse statement starting at line X

Solution: This error usually happens if a value in your .env file contains special characters (like # or $) and is not enclosed in quotes. To fix this, wrap the problematic value in double quotes. For example: MY_VARIABLE="value_with_#_character".

📈 Performance Tips

  1. Enable Caching: Set ENABLE_CACHING=true for faster repeated queries
  2. Adjust Rate Limits: Increase MAX_REQUESTS_PER_MINUTE if needed
  3. Optimize Logging: Use LOG_LEVEL=WARNING in production
  4. Hot Reload: Enable ENABLE_HOT_RELOAD=true for development

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new tools
  4. Submit a pull request

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

  • Google Gemini API team
  • MCP Protocol specification
  • Python community

📞 Support