TBNilles/advanced-windows-MCP-server

Advanced Windows MCP Server

A comprehensive Model Context Protocol (MCP) server designed for Windows environments, providing Claude Desktop with powerful system integration capabilities including file operations, task management, database queries, and system monitoring.

🚀 Features

📝 Personal Productivity

• Notes Manager: Create, read, list, and delete personal notes with persistent storage
• Task Manager: Create and manage tasks with priorities, due dates, and completion tracking
• Bookmark Manager: Save and organize web bookmarks with tags and descriptions

💻 System Operations

• File Operations: Advanced file system operations (read, write, copy, move, delete, search)
• System Commands: Execute safe Windows system commands with security restrictions
• Process Monitor: Monitor running Windows processes
• System Info: Retrieve detailed Windows system information
• Network Tools: Network configuration display and ping testing

🔧 Development Tools

• Git Operations: Git repository status, logs, and branch information
• HTTP Requests: Make HTTP requests to external APIs
• Database Queries: Direct SQL queries against the integrated SQLite database

📋 Prerequisites

• Windows 10/11 (required for Windows-specific commands)
• Go 1.19+ for building from source
• Claude Desktop for MCP integration
• Git (optional, for git operations tool)

🛠️ Installation

Option 1: Download Release (Recommended)

1. Download the latest mcp-server.exe from Releases
2. Place it in your desired directory
3. Configure Claude Desktop (see Configuration)

Option 2: Build from Source

# Clone the repository
git clone https://github.com/TBNilles/advanced-windows-mcp.git
cd advanced-windows-mcp

# Build the executable
go build -o mcp-server.exe main.go

⚙️ Configuration

Claude Desktop Setup

Add the server to your Claude Desktop configuration file:

Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "advanced-mcp-server": {
      "command": "C:\\path\\to\\your\\mcp-server.exe",
      "args": []
    }
  }
}

Database Location

The server automatically creates a SQLite database at:

%LOCALAPPDATA%\Claude\MCP\mcp_server.db

🎯 Available Tools

📖 Usage Examples

Notes Management

Create a note about project ideas
List all my notes
Read note #1
Delete note #2

Task Management

Create a task "Review MCP documentation" with high priority due 2024-12-25
List all pending tasks
Mark task #1 as completed

File Operations

List files in C:\Projects
Read the contents of config.txt
Create a new file with some content
Search for *.go files in the current directory

System Operations

Show system information
List running processes  
Get network configuration
Ping google.com

Development Tools

Show git status for this repository
Make an HTTP GET request to https://api.github.com
Query the database: SELECT * FROM notes WHERE title LIKE '%project%'

🏗️ Architecture

The server follows a modular architecture for maintainability and extensibility:

advanced-windows-mcp/
├── main.go                 # Application entry point
├── server/
│   └── server.go          # Core MCP server logic
├── database/
│   └── database.go        # SQLite database management
├── types/
│   ├── types.go           # Tool result types
│   └── mcp.go            # MCP protocol types
└── tools/
    ├── helpers.go         # Shared utilities
    ├── notes.go          # Notes management
    ├── tasks.go          # Task management
    ├── bookmarks.go      # Bookmark management
    ├── system.go         # System commands & info
    ├── network.go        # Network operations
    ├── database.go       # Database queries
    ├── http.go           # HTTP requests
    ├── fileOperations.go # File system operations
    └── gitOperations.go  # Git repository operations

🔒 Security Features

Command Whitelist

System commands are restricted to a safe whitelist:

• dir, echo, date, time, whoami
• systeminfo, tasklist, ipconfig
• netstat, ping, tree, type, ver, hostname

File Operation Safety

• Configurable size limits for file operations
• Path validation and sanitization
• Optional backup creation for file modifications
• Safety checks for dangerous operations (with override options)

Database Security

• Local SQLite database with no network exposure
• Parameterized queries to prevent SQL injection
• Read-only access patterns where appropriate

🚀 Development

Adding New Tools

1. Create a new file in the tools/ directory
2. Implement the tool function with signature:

   func ExecuteYourTool(arguments map[string]interface{}) (types.ToolResult, error)
   

3. Add the tool to the executeTool switch statement in server/server.go
4. Add the tool schema to registerTools in server/server.go

Building and Testing

# Run tests
go test ./...

# Build for production
go build -ldflags="-s -w" -o mcp-server.exe main.go

# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./mcp-server.exe

📊 Database Schema

Notes Table

CREATE TABLE notes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Tasks Table

CREATE TABLE tasks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    description TEXT,
    completed BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    due_date DATETIME,
    priority TEXT DEFAULT 'medium'
);

Bookmarks Table

CREATE TABLE bookmarks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    url TEXT NOT NULL,
    description TEXT,
    tags TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

🐛 Troubleshooting

Common Issues

Server won't start

• Check if the path in claude_desktop_config.json is correct
• Ensure the executable has proper permissions
• Verify Go dependencies with go mod tidy

Database errors

• Ensure write permissions in %LOCALAPPDATA%\Claude\MCP\
• Check disk space availability
• Try deleting the database file to recreate it

Tool validation errors

• Restart Claude Desktop completely
• Clear Claude Desktop cache if possible
• Verify the executable was rebuilt after code changes

Debug Mode

The server logs to stderr, which you can capture:

./mcp-server.exe 2> debug.log

🤝 Contributing

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

Code Style

• Follow standard Go conventions
• Use gofmt for formatting
• Add comments for exported functions
• Include error handling for all operations

📄 License

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

🙏 Acknowledgments

• Anthropic for the Model Context Protocol specification
• Claude Desktop for MCP integration
• The Go community for excellent tooling and libraries

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: MCP Specification

🔗 Related Projects

• Model Context Protocol - Official MCP documentation
• Claude Desktop - AI assistant with MCP support
• MCP Servers - Official MCP server examples

Built with ❤️ for the Claude Desktop and MCP community