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)

Download the latest DXT file from Releases
Open Claude Desktop
Go to Settings → Developer → MCP Servers
Drag & Drop the DXT file onto the extensions screen
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

MCP Client (Claude Desktop) → FastMCP Server
Server → NotepadPPController → Windows API
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"

Restart Claude Desktop after configuration
Check logs in Claude developer console
Verify Notepad++ is running on the system
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

Run demonstration script first: python demonstration_test.py
Check existing issues on GitHub
Include error logs and system information
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