Windows Operations MCP

FastMCP Python MCPB License Status

A comprehensive Windows system operations MCP server implementing the FastMCP 2.12.3 protocol with full MCPB (MCP Bundle) packaging support.

✨ What's New (October 2025)

✅ MCPB Migration Complete: Fully migrated from DXT to MCPB packaging
✅ Enhanced Test Coverage: 16+ test modules with comprehensive coverage
✅ GitHub Actions CI/CD: Automated builds and testing
✅ Improved Tools: Enhanced JSON and media metadata tools
✅ Better Error Handling: Improved command execution and error reporting
✅ PowerShell Build Automation: One-command package building
✅ Production Ready: Validated, tested, and ready for deployment

Related MCP server: Claude Desktop Commander MCP

🚨 IMPORTANT: MCPB Migration Complete

This repository has been fully migrated from DXT to MCPB (MCP Bundle) standards as of October 2025. All tooling, configuration, and packaging now follows the latest MCPB specifications with FastMCP 2.12.3 compatibility.

Migration Summary

Component	Old (DXT)	New (MCPB)	Status
CLI Tool	`dxt` commands	`mcpb` commands	✅ Migrated
Config File	`dxt.json`	`mcpb.json`	✅ Migrated
Manifest	`dxt_manifest.json`	`mcpb/manifest.json`	✅ Migrated
Package Format	`.dxt` packages	`.mcpb` packages	✅ Migrated
Documentation	DXT guides	MCPB guides	✅ Migrated
Build Scripts	Manual build	PowerShell automation	✅ Migrated
CI/CD	None	GitHub Actions	✅ Added

🚀 Key Features

✅ MCPB Packaging & Distribution

Full MCPB compliance with proper manifest structure (v0.2 format)
Automated AI-generated manifests for optimal configuration
PowerShell build automation with validation and signing support
GitHub Actions CI/CD for automated package building
Comprehensive exclusion patterns for clean repository archiving
Production-ready packaging validated and tested

✅ Windows System Operations

Windows Services Management: Start, stop, restart, list services with filtering
Windows Event Log Tools: Query, export, monitor, and clear event logs
Windows Performance Monitoring: Real-time performance counters and system metrics
Windows Permissions Management: File/directory permissions analysis and modification

✅ Core Operations

PowerShell & CMD Execution: Reliable command execution with output capture and error handling
File Operations: Create, read, write, move, copy files and directories with comprehensive error handling
Archive Management: Create/extract ZIP archives with intelligent exclusion patterns
JSON Tools: Parse, validate, format, and query JSON files with JSONPath support
Media Metadata: Extract metadata from images, audio, and video files
System Information: Comprehensive OS, hardware, and environment reporting
Health Monitoring: Built-in health checks and diagnostic tools

🏗️ Installation

Option 1: MCPB Package (Recommended)

Download the latest release from the GitHub Releases page
Drag the to Claude Desktop for automatic installation
Follow the configuration prompts to set up your preferences
Restart Claude Desktop to complete the installation

Option 2: Manual Installation

# Clone the repository git clone https://github.com/sandraschi/windows-operations-mcp.git cd windows-operations-mcp # Install Python dependencies pip install -r requirements.txt # Install as editable package pip install -e . # Configure for Claude Desktop # Add to claude_desktop_config.json: { "mcpServers": { "windows-operations": { "command": "python", "args": ["-m", "windows_operations_mcp"], "cwd": "src" } } }

🛠️ Development & Building

Prerequisites

# Install MCPB CLI (official toolchain) npm install -g @anthropic-ai/mcpb # Install Python dependencies (EXACT VERSIONS) pip install "fastmcp>=2.12.0,<3.0.0" pip install -r requirements.txt

Repository Structure

windows-operations-mcp/ ├── mcpb/ # MCPB configuration and manifest │ ├── manifest.json # AI-generated runtime configuration │ └── assets/ # Icons, screenshots ├── src/ # Python source code │ └── windows_operations_mcp/ # Main Python package │ ├── __init__.py │ ├── server.py # Main server entry point │ └── tools/ # Tool modules ├── scripts/ # Build and utility scripts │ └── build-mcp-package.ps1 # MCPB package builder ├── docs/ # Documentation ├── requirements.txt # Python dependencies └── README.md # This file

Building MCPB Packages

# Show help and available options .\scripts\build-mcp-package.ps1 -Help # Build and sign the package (default behavior) .\scripts\build-mcp-package.ps1 # Build without signing (for development/testing) .\scripts\build-mcp-package.ps1 -NoSign # Specify custom output directory .\scripts\build-mcp-package.ps1 -OutputDir "C:\builds"

Local Development Workflow

# 1. AI-generate manifest.json (place in mcpb/manifest.json) # ENSURE: fastmcp>=2.12.0 in requirements.txt # ENSURE: cwd: "src" and PYTHONPATH: "src" in mcp_config # 2. Validate manifest cd mcpb mcpb validate manifest.json # 3. Build MCPB package mcpb pack . ../dist/package.mcpb # 4. Test installation # Drag dist/*.mcpb to Claude Desktop

🎯 Available Tools

Windows Services Management

list_windows_services - List services with filtering
start_windows_service - Start Windows services
stop_windows_service - Stop Windows services
restart_windows_service - Restart Windows services

Windows Event Log Tools

query_windows_event_log - Query event logs with filtering
export_windows_event_log - Export event logs to files
clear_windows_event_log - Clear event logs with backup
monitor_windows_event_log - Real-time event log monitoring

Windows Performance Monitoring

get_windows_performance_counters - Query performance counters
monitor_windows_performance - Monitor performance over time
get_windows_system_performance - Comprehensive system metrics

Windows Permissions Management

get_file_permissions - Analyze file/directory permissions
set_file_permissions - Modify file permissions
analyze_directory_permissions - Bulk permission analysis
fix_file_permissions - Fix common permission issues

Archive Management (with exclusions)

create_archive - Create archives with intelligent exclusions
extract_archive - Extract archives
list_archive - List archive contents

Core Operations

run_powershell_tool - Execute PowerShell commands
run_cmd_tool - Execute CMD commands
read_file / write_file - File operations
get_system_info / health_check - System monitoring
get_help - Tool documentation and help

⚙️ Configuration

User Configuration Options

When installing the MCPB package, you can configure:

Working Directory: Default directory for file operations
Log Level: Logging verbosity (DEBUG, INFO, WARNING, ERROR)
Performance Monitoring: Enable detailed metrics collection

Environment Variables

The server respects these environment variables:

LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
PYTHONPATH: Python module search path
PYTHONUNBUFFERED: Force unbuffered output

🔧 Troubleshooting

Extension Fails to Start

Symptoms: Extension shows as failed in Claude Desktop settings.

Common Causes:

Python Path Issues: Incorrect PYTHONPATH configuration
Missing Dependencies: Required packages not installed
Permission Issues: Insufficient permissions for operations

Solutions:

Check Python Path: Ensure PYTHONPATH includes the src directory
Verify Dependencies: Run pip install -r requirements.txt
Check Logs: Review %APPDATA%\Claude\logs\mcp-server-windows-operations.log

Manual Configuration Workaround

If the MCPB package fails to start, add a manual entry to claude_desktop_config.json:

{ "mcpServers": { "windows-operations-manual": { "command": "python", "args": ["C:/Users/{YOUR_USERNAME}/AppData/Roaming/Claude/Claude Extensions/local.mcpb.sandraschi.windows-operations-mcp/src/windows_operations_mcp/server.py"], "cwd": "C:/Users/{YOUR_USERNAME}/AppData/Roaming/Claude/Claude Extensions/local.mcpb.sandraschi.windows-operations-mcp/src", "env": { "PYTHONPATH": "C:/Users/{YOUR_USERNAME}/AppData/Roaming/Claude/Claude Extensions/local.mcpb.sandraschi.windows-operations-mcp/src", "PYTHONUNBUFFERED": "1" } } } }

🧪 Testing

Test Coverage

The project maintains comprehensive test coverage across all components:

Unit Tests: 16+ test modules covering all tools and utilities
Integration Tests: MCP server integration testing
Coverage Reports: HTML coverage reports generated automatically
Test Categories: Archive tools, file operations, JSON tools, media tools, command execution

Running Tests

# Run all tests python -m pytest # Run with coverage report python -m pytest --cov=src --cov-report=html --cov-report=term # Run specific test categories python -m pytest tests/unit/tools/ -v # Tool tests python -m pytest tests/unit/utils/ -v # Utility tests python -m pytest tests/integration/ -v # Integration tests # Run with verbose output python -m pytest -vv # Run PowerShell test script .\tests\run_tests.ps1

Manual Testing

# Test MCP server directly cd src python -m windows_operations_mcp # Test specific tools python -c " from windows_operations_mcp.tools.windows_services import list_windows_services result = list_windows_services() print('Services found:', len(result.get('services', []))) " # Test package build .\scripts\build-mcp-package.ps1 -NoSign

🤝 Contributing

Development Setup

Fork the repository on GitHub
Clone your fork locally
Create a feature branch: git checkout -b feature/new-tool
Install dependencies: pip install -r requirements.txt
Run tests: python -m pytest
Make your changes with proper documentation
Submit a pull request

Adding New Tools

Create tool module in src/windows_operations_mcp/tools/
Implement tool functions with proper decorators and documentation
Add registration function that registers tools with FastMCP
Register in main server by importing and calling the registration function
Add tests in tests/unit/tools/
Update documentation in this README

Code Standards

Type Hints: Use comprehensive type annotations
Error Handling: Implement proper exception handling with logging
Documentation: Use self-documenting multiline decorators
Testing: Maintain >90% test coverage
Security: Validate inputs and handle sensitive operations safely

📋 MCPB Compliance Checklist

✅ MCPB Manifest: Proper mcpb/manifest.json with AI generation (v0.2 format)
✅ Python Path Configuration: Correct PYTHONPATH and cwd settings
✅ FastMCP 2.12.3: Latest version requirement enforced
✅ Exclusion Patterns: Intelligent artifact exclusion for archiving
✅ Self-Documenting Tools: Comprehensive parameter and return documentation
✅ Error Handling: Robust error handling with detailed diagnostics
✅ Build Process: Automated MCPB package building with PowerShell scripts
✅ CI/CD Integration: GitHub Actions for automated testing and builds
✅ Test Coverage: Comprehensive unit and integration tests
✅ Documentation: Complete guides and examples

📄 License

MIT License - see LICENSE file for details.

🆘 Support & Resources

Getting Help

Issues: GitHub Issues - Bug reports and feature requests
Discussions: GitHub Discussions - Community support
Documentation: Check the docs/ directory for comprehensive guides

Documentation

📖 Documentation Index - Complete documentation guide
📖 MCPB Building Guide - Package building instructions
📖 Getting Started - Quick start guide
📖 Examples - Usage examples
📖 Repository Status - Current project status

Quick Links

FastMCP Documentation: https://github.com/jlowin/fastmcp
Model Context Protocol: https://modelcontextprotocol.io
Claude Desktop: https://claude.ai/desktop

📊 Project Status

Version: 0.2.0 🎉 (MCPB Release)
Status: ✅ Production Ready
Health Score: 9.0/10
Last Updated: October 8, 2025

See REPOSITORY_STATUS_REPORT.md for detailed status information.

Built with ❤️ using FastMCP 2.12.3 and MCPB standards
Providing reliable Windows system operations through the Model Context Protocol