File Operation MCP Server

A Model Context Protocol (MCP) based file operation server, providing file statistics, list queries, image compression, and various system utilities.

✨ Features

• 📊 File Statistics - Count files in a specified folder

• 📋 File Listing - Get detailed information of all files in a folder

• 🖼️ Image Compression - High-quality image compression, supporting multiple formats

• 🗜️ File Compression - Create ZIP, TAR, TAR.GZ archive files

• 📦 File Extraction - Extract ZIP, TAR, TAR.GZ archive files

• 📂 File Copy - Copy files or folders to a specified location

• 🔄 File Move - Move files or folders to a specified location

• 📄 PDF Merge - Merge multiple PDF files into one

• ✂️ PDF Split - Split PDF files by page or range

• 🖼️ PDF to Image - Convert PDF pages to JPEG/PNG images

• 🔒 Secure & Reliable - Comprehensive error handling and parameter validation

• ⚡ High Performance - Built with TypeScript and powered by Bun for speed.

🛠️ Technology Stack

• TypeScript - Type-safe JavaScript

• Bun - High-performance JavaScript runtime, used for running the server.

• MCP SDK - Official Model Context Protocol SDK

• Sharp - High-performance image processing library

• PDF-lib - Pure JavaScript PDF processing library, supports merging and splitting

• PDF2pic - PDF to image conversion tool

• Mammoth - Word document processing library

• Puppeteer - Headless browser, used for PDF generation

• Archiver - File compression library, supports ZIP, TAR, etc.

• Extract-Zip - ZIP file extraction library

• TAR - TAR format file processing library

• fs-extra - Enhanced file system operations

• Zod - TypeScript-first data validation

📦 Installation

Environment Requirements

• Node.js >= 18.0.0 (for pnpm build steps)

• Bun (recommended for running the server)

• pnpm (recommended for package installation and build)

Clone Project

Install Dependencies

Build Project

🔌 Transport Method Comparison

This project supports two MCP transport methods. You can choose the appropriate method based on your usage scenario:

📊 Stdio vs SSE Comparison Table

🎯 Recommended Use Cases

Choose Stdio if you need:

• 🏠 Local Development: Simple personal desktop tools

• 🔒 Single User: Applications for personal use only

• ⚡ Low Latency: Extremely high response time requirements

• 📦 Simple Deployment: Don't want to configure an HTTP server

• 💾 Resource Saving: Limited system resources

Choose SSE if you need:

• 🌐 Remote Access: Connect to the server over a network

• 👥 Multi-user: Team-shared server

• 🔄 High Availability: Requires load balancing and failover

• 🐛 Easy Debugging: Convenient debugging tools during development

• 📈 Scalability: May need horizontal scaling in the future

• 🔍 Monitoring Needs: Requires detailed service monitoring

🔧 Performance Comparison

Stdio Architecture

SSE Architecture

🛠️ Code Difference Example

Stdio Startup

SSE Startup

💡 Recommendation: If you are a single user and only need local use, choose Stdio; if you need team collaboration or remote access, choose SSE.

⚙️ Stdio Configuration

Claude Desktop Configuration

Add the following configuration to Claude Desktop's configuration file:

Configuration File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration Content:

⚠️ Note: Please replace path/to/file-operation-mcp with the actual project path

Cursor IDE Configuration

⚙️ SSE Configuration

Starting the SSE Server

First, start the HTTP server:

The server will be available at:

• Health check: http://localhost:3000/health

• MCP endpoint: http://localhost:3000/sse

Configuration

Environment Variables

Check server health status

curl http://localhost:3000/health

Example response

{ "status": "ok", "message": "MCP File Operation Server is running", "timestamp": "2024-01-01T12:00:00.000Z" }

Cursor IDE Configuration

SSE Endpoint Description

• SSE Connection: http://localhost:3000/sse - Primary MCP connection endpoint

• Message Handling: http://localhost:3000/messages - Handles JSON-RPC messages

• Health Check: http://localhost:3000/health - Server status check

• Port Configuration: Can be modified via PORT environment variable, defaults to 3000

⚠️ Note: SSE mode requires manual server startup first, then client connection configuration.

🚀 Usage

After configuration, restart Claude Desktop to use the following features in your conversations:

1. File Counting (count-files)

Counts the number of files in a specified folder, defaults to desktop files.

Parameters:

• folderPath (Optional): Folder path, defaults to desktop

Example:

2. File Listing (list-files)

Gets detailed information of all files in a specified folder, including filename, type, and size.

Parameters:

• folderPath (Optional): Folder path, defaults to desktop

• includeHidden (Optional): Whether to include hidden files, defaults to false

Example:

3. Image Compression (compress-image)

Compresses specified image files, supports various formats and custom parameters.

Parameters:

• imagePath: Image file path (Required)

• quality (Optional): Compression quality (1-100), defaults to 80

• maxWidth (Optional): Maximum width limit

• maxHeight (Optional): Maximum height limit

• outputPath (Optional): Output path, defaults to original filename with _compressed suffix

Supported Formats:

• JPEG/JPG

• PNG

• WebP

• TIFF

• GIF

Example:

4. File Compression (create-archive)

Compresses files or folders into ZIP, TAR, or TAR.GZ format.

Parameters:

• files: Array of file/folder paths to compress (Required)

• outputPath: Output archive file path (Required)

• format (Optional): Compression format (zip, tar, tar.gz), defaults to zip

• compressionLevel (Optional): Compression level (0-9), defaults to 6

Supported Formats:

• ZIP - General compression format, best compatibility

• TAR - Common Unix/Linux format, no compression

• TAR.GZ - TAR format + GZIP compression, high compression ratio

Example:

5. File Extraction (extract-archive)

Extracts ZIP, TAR, or TAR.GZ files to a specified directory.

Parameters:

• archivePath: Archive file path (Required)

• extractTo: Target directory for extraction (Required)

• overwrite (Optional): Whether to overwrite existing files, defaults to false

Supported Formats:

• ZIP - .zip file

• TAR - .tar file

• TAR.GZ - .tar.gz, .tgz files

Example:

Notes:

• Checks if the target directory is empty before extraction (unless overwrite=true)

• Supports automatic detection of compression format

• Displays extracted file count and total size

• Maintains original file structure during extraction

6. File Copy (copy-files)

Copies a file or folder to a specified location, keeping the original file unchanged.

Parameters:

• sourcePath: Source file/folder path (Required)

• targetPath: Target path (Required)

• overwrite (Optional): Whether to overwrite existing files, defaults to false

• preserveTimestamps (Optional): Whether to preserve timestamps, defaults to true

Features:

• Supports file and folder copying

• Recursively copies entire directory structure

• Option to preserve original timestamps

• Security checks prevent accidental overwrites

• Displays copy details and file statistics

Example:

7. File Move (move-files)

Moves a file or folder to a specified location, equivalent to a cut operation.

Parameters:

• sourcePath: Source file/folder path (Required)

• targetPath: Target path (Required)

• overwrite (Optional): Whether to overwrite existing files, defaults to false

Features:

• Supports file and folder moving

• Atomic operation, ensuring data integrity

• Automatic verification of move completion

• Prevents source and target paths from being the same

• Cross-filesystem move support

Example:

Notes:

• Move operation deletes the original file/folder

• Supports cross-partition/drive moves

• Verifies target directory permissions before moving

• Validates results after operation completion

8. PDF Merge (merge-pdf)

Merges multiple PDF files into a single complete PDF document.

Parameters:

• inputPaths: Array of PDF file paths (Required)

• outputPath: Output PDF file path (Required)

• title (Optional): Title of the merged PDF

Features:

• Supports merging any number of PDF files

• Maintains original page format and quality

• Automatically sets document metadata

• Detailed merge statistics report

• Automatically adds .pdf extension

Example:

9. PDF Split (split-pdf)

Splits a PDF file into multiple independent files, supporting splitting by page or custom range.

Parameters:

• inputPath: Input PDF file path (Required)

• outputDir: Output directory (Required)

• splitMode (Optional): Split mode - pages (one file per page) or ranges (split by range), defaults to pages

• ranges (Optional): Array of page ranges, e.g., ["1-3", "4-6"], only required for ranges mode

• prefix (Optional): Output filename prefix, defaults to original filename

Features:

• Two splitting modes: page-by-page splitting or range splitting

• Flexible page range settings

• Maintains original page format

• Automatic file naming and numbering

• Detailed splitting statistics

Example:

• Before splitting

• After splitting

10. PDF to Image (pdf-to-image)

Converts PDF pages to high-quality image files, supports various formats and custom settings.

Parameters:

• inputPath: Input PDF file path (Required)

• outputDir: Output directory (Required)

• format (Optional): Image format - jpeg or png, defaults to jpeg

• quality (Optional): Image quality 1-100, defaults to 80

• dpi (Optional): Resolution DPI 50-600, defaults to 150

• pages (Optional): Page range, e.g., "1-3" or "1,3,5", defaults to all pages

• prefix (Optional): Output filename prefix

Features:

• Supports JPEG and PNG formats

• Adjustable image quality and resolution

• Flexible page selection (range, list, single page)

• Batch processing of all pages

• Detailed conversion statistics

Example:

Notes:

• PDF to image conversion requires system support for ImageMagick or GraphicsMagick

• High resolution settings will increase file size and processing time

• PNG format files are larger but higher quality

• Recommended resolution: 150 DPI for screen display, 300 DPI for printing

11. SQLite Database Operations (query-sqlite)

Performs various SQLite database operations including creating databases, executing queries, importing/exporting CSV, getting schema info, and more.

Parameters:

• database_path: SQLite database file path (Required)

• operation: Operation type (Required) - create_db, execute_query, import_csv, export_csv, get_schema, drop_table, backup, restore, transaction, get_stats

• query (Optional): SQL query statement (for execute_query and transaction operations)

• table_name (Optional): Table name (for drop_table, export_csv, etc. operations)

• csv_path (Optional): CSV file path (for import_csv and export_csv operations)

• backup_path (Optional): Backup file path (for backup and restore operations)

Features:

• Create new SQLite databases

• Execute SELECT, INSERT, UPDATE, DELETE and other SQL queries

• Import data from CSV files to database tables

• Export database tables as CSV files

• Get database table schema information

• Delete database tables

• Backup and restore database files

• Execute transactions to ensure data consistency

• Get database statistics

Example:

12. Advanced File Compression (compress-files)

Compresses or decompresses files with various formats and options including ZIP, TAR, GZIP, BZIP2.

Parameters:

• source_paths: File or directory paths to compress (Required, space-separated)

• destination_path: Output archive file path (Required)

• operation: Operation type (Required) - compress, decompress, info, update, test, encode

• format (Optional): Compression format - zip, tar, gzip, bzip2, defaults to zip

• compression_level (Optional): Compression level 0-9, defaults to 6

• password (Optional): Password for ZIP archives

• exclude_patterns (Optional): File/directory patterns to exclude (space-separated)

• encoding (Optional): Filename encoding

Features:

• Supports multiple compression formats (ZIP, TAR, GZIP, BZIP2)

• Adjustable compression levels

• ZIP archive password protection

• File exclusion patterns

• View compressed file information

• Test compressed file integrity

• Decompress archive files

Example:

13. Text Processing (process-text)

Performs various text processing operations including sorting lines, removing duplicates, filtering patterns, replacing text, counting words/lines, and more.

Parameters:

• file_path: Path to the text file to process (Required)

• operation: Operation type (Required) - sort, dedupe, filter, replace, count, convert_encoding, split, merge, case_transform, prefix_suffix, tabs_spaces, trim

• sort_order (Optional): Sort order asc/desc (for sort operation)

• filter_pattern (Optional): Filter pattern (for filter operation)

• is_regex (Optional): Whether it's a regex, defaults to false (for filter and replace operations)

• find_text (Optional): Text to find (for replace operation)

• replace_text (Optional): Replacement text (for replace operation)

• merge_paths (Optional): File paths to merge (for merge operation)

• case_option (Optional): Case transformation option upper/lower/capitalize (for case_transform operation)

• prefix (Optional): Line prefix (for prefix_suffix operation)

• suffix (Optional): Line suffix (for prefix_suffix operation)

• tab_size (Optional): Tab size, defaults to 4 (for tabs_spaces operation)

• output_path (Optional): Output file path

Features:

• Sort text lines (ascending/descending)

• Remove duplicate lines

• Text filtering (plain text/regex)

• Text replacement (plain text/regex)

• Count words, lines, characters

• Text case transformation

• Add line prefixes/suffixes

• Tab to space conversion

• Merge multiple text files

• Trim leading/trailing whitespace

Example:

📸 Feature Demo

File Listing Query

Defaults to querying desktop files, or specify a path:

File Count Statistics

Quickly count files in a specified directory:

Image Compression Feature

High-quality image compression, supports custom parameters:

🔧 Development

Development Mode

Code Formatting

Code Linting

Start Server

⚠️ Notes

1. Permission Requirements: Ensure Node.js has access to the target folders

2. Path Format:

   • macOS/Linux: /Users/username/path

   • Windows: C:\Users\username\path

3. Image Formats: Only common image formats (JPEG, PNG, WebP, TIFF, GIF) are supported

4. Archive Formats: Supports ZIP, TAR, TAR.GZ for compression and extraction

5. File Operations: Copy and move operations support files and folders

6. PDF Processing: PDF merge, split, and convert-to-image functions are purely JavaScript-based

7. Image Conversion: PDF to image conversion requires ImageMagick or GraphicsMagick system support

8. File Permissions: Ensure appropriate permissions for source files and target directories

9. Overwrite Protection: By default, existing files are not overwritten; explicit setting is required

10. File Size: Large file processing may take longer

11. Debugging Output: Use console.error() instead of console.log() to avoid interfering with the MCP protocol

🐛 Troubleshooting

Common Issues

1. Server Startup Failure

Solution: Ensure bun install (or pnpm install) and pnpm build have been run.

2. Permission Error

Solution: Check folder access permissions, or use a path with appropriate permissions.

3. Path Does Not Exist

Solution: Confirm the path is correct, use absolute paths.

4. Unsupported Image Format

Solution: Use a supported image format (jpg, png, webp, tiff, gif).

5. Archive Creation Failure

Solution:

• Check if file paths are correct

• Ensure write permissions for the output directory

• Check for sufficient disk space

6. File Extraction Failure

Solution: Set overwrite=true or clear the target directory.

7. Unsupported Archive Format

Solution: Use a supported format (.zip, .tar, .tar.gz, .tgz).

8. File Copy Failure

Solution: Set overwrite=true or choose a different target path.

9. File Move Failure

Solution: Ensure source and target paths are different.

10. Insufficient Permissions

Solution:

• Check access permissions for source files and target directories

• Ensure sufficient disk space

• Avoid moving critical system files

11. Corrupted PDF File

Solution:

• Check if the PDF file is complete and undamaged

• Confirm the PDF file is not password protected

• Try verifying the file with another PDF viewer

12. PDF to Image Conversion Failure

Solution:

• Ensure ImageMagick or GraphicsMagick is installed on the system

• Check system PATH environment variable configuration

• Lower DPI settings or reduce the number of pages

13. Page Range Error

Solution:

• Check the actual number of pages in the PDF file

• Ensure page range format is correct (e.g., "1-5", "1,3,5")

• Page numbering starts from 1, not 0

Debugging Tips

1. Check Claude Desktop's developer console

2. Check server log output

3. Use MCP Inspector for debugging