Notepad++ MCP Server

FastMCP 2.12 compatible MCP server for comprehensive Notepad++ automation and control.

✨ 15 powerful tools including advanced tab and session management 🧪 18 comprehensive tests with real Windows API integration 🎯 Production-ready with structured logging and error handling

🚀 Installation & Setup

📦 Option 1: DXT Installation (Recommended)

1. Download the latest DXT file from Releases
2. Open Claude Desktop
3. Go to Settings → Developer → MCP Servers
4. Drag & Drop the DXT file onto the extensions screen
5. Restart Claude Desktop - the server will auto-install and configure

🐍 Option 2: Python Installation

# Install from PyPI
pip install notepadpp-mcp

# Or install from source
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp
pip install -e .

⚙️ Claude Desktop Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "notepadpp-mcp",
      "args": []
    }
  }
}

🔧 Manual Configuration (if needed)

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "python",
      "args": ["-m", "notepadpp_mcp.tools.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

📋 Requirements

🖥️ System Requirements

• Windows 10/11 (64-bit)
• Notepad++ 8.0+ installed and accessible
• Python 3.10+ with pip
• pywin32 for Windows API integration

🛠️ Dependencies

• FastMCP 2.12+ - MCP framework
• pywin32 - Windows API bindings
• psutil - System monitoring
• pathlib - Path operations

🚨 Important Notes

• Notepad++ must be installed on the system
• Server requires Windows API access (pywin32)
• First run may require Notepad++ to be started manually

🎯 New in v1.0: Advanced Workspace Management

📑 Tab Management Tools

Organize and navigate multiple open files efficiently:

• List all tabs: See filenames, modification status, and active tab
• Switch tabs: Jump to any tab by index (0-based)
• Close tabs: Remove tabs individually or current tab

💾 Session Management Tools

Save and restore your entire workspace:

• Save sessions: Preserve all open files and cursor positions
• Load sessions: Restore complete workspace state
• List sessions: Browse saved workspace configurations

💡 Usage Examples

# Get comprehensive help about all tools
get_help()

# List all open tabs
list_tabs()

# Save current workspace
save_session("my_project_session")

# Load a saved session
load_session("my_project_session")

# Switch to tab 2
switch_to_tab(2)

📁 Project Structure

notepadpp-mcp/
├── src/notepadpp_mcp/
│   ├── tools/          # MCP server implementation
│   ├── docs/           # Documentation and examples
│   ├── tests/          # Test suite
│   └── dxt/            # DXT packaging configuration
├── pyproject.toml      # Package configuration
├── README.md           # This file
└── LICENSE             # MIT license

📚 Documentation

• Complete API Documentation - Comprehensive guide
• Product Requirements Document - Vision and roadmap
• Configuration Examples - Integration templates

🛠️ Tools Overview (15 Total)

Category	Tools	Description
File Operations	4	Create, open, save, and inspect files
Text Operations	2	Insert and search text content
Status & Info	3	Monitor system and document state
Tab Management	3	Organize and navigate multiple files
Session Management	3	Save and restore workspace states

Total: 15 production-ready tools with comprehensive Windows API integration.

⚡ Features

📁 File Operations (4 tools)

• open_file - Open files in Notepad++
• new_file - Create new files
• save_file - Save current file
• get_current_file_info - Get file metadata

📝 Text Operations (2 tools)

• insert_text - Insert text at cursor position
• find_text - Search text with case sensitivity options

📊 Status & Information (3 tools)

• get_status - Notepad++ status and window info
• get_system_status - Comprehensive system diagnostics
• get_help - Hierarchical help system

📑 Tab Management (3 tools) ✨ NEW

• list_tabs - List all open tabs with metadata
• switch_to_tab - Switch between tabs by index
• close_tab - Close tabs by index or current tab

💾 Session Management (3 tools) ✨ NEW

• save_session - Save workspace to named session
• load_session - Load saved sessions
• list_sessions - List all saved sessions

🔧 Core Capabilities

• 🎯 Windows Integration: Native Windows API with pywin32
• ⚡ FastMCP 2.12: Latest MCP framework compliance
• 📝 Structured Logging: Professional error handling
• 🧪 Comprehensive Testing: 18 tests covering all tools
• 📚 Self-Documenting: Built-in help system

🛠️ Development

# Clone and install
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp
pip install -e .[dev]

# Run comprehensive tests
python -m pytest src/notepadpp_mcp/tests/

# Format code
black src/

# Test real Notepad++ integration
python demonstration_test.py

# Development helper
python dev.py test|format|build|validate-dxt

🧪 Testing

• 18 comprehensive tests covering all tools
• Real Windows API testing with actual Notepad++ integration
• Demonstration script (demonstration_test.py) tests live functionality
• CI/CD ready with automated testing pipeline

🏗️ Architecture

🎯 Core Components

• NotepadPPController - Windows API integration layer
• FastMCP Server - MCP protocol implementation
• Tool Decorators - Automatic tool registration
• Structured Logging - Professional error handling

🔧 Integration Flow

1. MCP Client (Claude Desktop) → FastMCP Server
2. Server → NotepadPPController → Windows API
3. Windows API → Notepad++ Application → User Interface

📁 File Structure

src/notepadpp_mcp/
├── tools/server.py     # Main MCP server (966 lines)
├── tests/              # Comprehensive test suite
├── docs/               # Documentation and examples
└── dxt/                # DXT packaging configuration

🐛 Troubleshooting

❌ Common Issues

"Notepad++ not found"

# Check if Notepad++ is installed
python demonstration_test.py

# Install Notepad++
# Download from: https://notepad-plus-plus.org/downloads/
# Or via Chocolatey: choco install notepadplusplus

"Windows API not available"

# Install pywin32
pip install pywin32

# Restart Python environment
# Try running demonstration script again
python demonstration_test.py

"Server not connecting"

{
  "mcpServers": {
    "notepadpp-mcp": {
      "command": "python",
      "args": ["-m", "notepadpp_mcp.tools.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

"Tools not appearing in Claude"

1. Restart Claude Desktop after configuration
2. Check logs in Claude developer console
3. Verify Notepad++ is running on the system
4. Run demonstration script to test functionality

🆘 Getting Help

Run Diagnostics

# Test all functionality
python demonstration_test.py

# Check tool availability
python -c "from notepadpp_mcp.tools.server import app; print('Tools:', len(app._tools))"

Debug Mode

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Run server with debug output
python -m notepadpp_mcp.tools.server

Manual Testing

# Test individual tools
from notepadpp_mcp.tools.server import get_status, get_help

# Get status
status = await get_status()
print("Status:", status)

# Get help
help_info = await get_help()
print("Help:", help_info)

🤝 Contributing

📝 Development Setup

# Clone repository
git clone https://github.com/sandraschi/notepadpp-mcp.git
cd notepadpp-mcp

# Install development dependencies
pip install -e .[dev]

# Run tests
python -m pytest

# Format code
black src/

# Build DXT package
python dev.py build

🐛 Reporting Issues

1. Run demonstration script first: python demonstration_test.py
2. Check existing issues on GitHub
3. Include error logs and system information
4. Test with different Notepad++ versions if possible

💡 Feature Requests

• Check existing tools in the tools overview
• Consider Windows API limitations
• Test with real Notepad++ workflows
• Follow FastMCP 2.12 patterns

📜 Changelog

v1.0.0 - Current Release

• ✅ 15 comprehensive tools for Notepad++ automation
• ✅ Real Windows API integration with pywin32
• ✅ Advanced tab and session management
• ✅ 18 comprehensive tests with full coverage
• ✅ DXT packaging for easy installation
• ✅ Production-ready error handling and logging

Planned Features

• Multi-instance support for multiple Notepad++ windows
• Plugin integration for extended functionality
• Configuration files for custom settings
• Batch operations for multiple file processing

📄 License

MIT - see LICENSE