File Operation MCP Server
by Yussefgafer
README.md
# File Operation MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://bun.sh/)
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
```bash
git clone https://github.com/lxKylin/file-operation-mcp.git
cd file-operation-mcp
```
### Install Dependencies
```bash
bun install # Use Bun for faster installation
pnpm install # (Alternative if Bun is not preferred, or for specific build dependencies)
```
### Build Project
```bash
pnpm build
## āļø Configuration
### Environment Variables
| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `TIME_LIMIT` | Default time limit for operations (seconds) | `120` | `300` |
| `MAX_TIME_LIMIT` | Maximum allowed time limit (seconds) | `600` | `1800` |
### Example Usage
```bash
# Set custom time limit (5 minutes)
TIME_LIMIT=300 bun run start
# Set maximum time limit (30 minutes)
MAX_TIME_LIMIT=1800 bun run start
```
## š 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
| Feature | Stdio | SSE |
|---|---|---|
| **Transfer Protocol** | Inter-process Communication (IPC) | HTTP/HTTPS |
| **Connection Method** | stdin/stdout | Server-Sent Events |
| **Multi-client Support** | ā 1-to-1 connection | ā
Many-to-1 connection |
| **Remote Access** | ā Local only | ā
Supported |
| **Deployment Complexity** | ā
Simple | ā Requires HTTP server |
| **Resource Usage** | ā
Low | ā Relatively higher |
| **Debugging Convenience** | ā Difficult | ā
Easy (HTTP tools) |
| **Network Traversal** | ā Not supported | ā
Supported |
| **Load Balancing** | ā Not supported | ā
Supported |
| **Monitoring Capabilities** | ā Limited | ā
Rich (health checks, etc.) |
| **Latency** | ā
Very Low (~1-5ms) | ā Slightly Higher (~10-50ms) |
### šÆ 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
```
Client <ā> Server Process (Direct IPC)
Latency: 1-5ms | Memory: Low | CPU: Low
```
#### SSE Architecture
```
Client <ā> HTTP Server <ā> MCP Server
Latency: 10-50ms | Memory: Medium | CPU: Medium
```
### š ļø Code Difference Example
#### Stdio Startup
```typescript
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('Stdio MCP server started');
```
#### SSE Startup
```typescript
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import express from 'express';
const app = express();
app.get('/sse', async (req, res) => {
const transport = new SSEServerTransport('/messages', res);
await server.connect(transport);
});
app.listen(3000, () => {
console.error('SSE MCP server started on port 3000');
});
```
> š” **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:**
```json
{
"mcpServers": {
"file-operation-mcp": {
"command": "node",
"args": ["path/to/file-operation-mcp/dist/index.js"],
"cwd": "path/to/file-operation-mcp",
"env": {
"NODE_ENV": "production"
}
}
}
}
```
> ā ļø **Note**: Please replace `path/to/file-operation-mcp` with the actual project path
### Cursor IDE Configuration
```json
{
"mcpServers": {
"file-operation-mcp": {
"command": "node",
"args": ["path/to/file-operation-mcp/dist/index.js"]
}
}
}
```
## āļø SSE Configuration
### Starting the SSE Server
First, start the HTTP server:
```bash
bun start
# Or using pnpm (less recommended for runtime due to Bun's performance)
```
The server will be available at:
- Health check: http://localhost:3000/health
- MCP endpoint: http://localhost:3000/sse
## Configuration
### Environment Variables
| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `TIME_LIMIT` | Default time limit for operations (seconds) | `120` | `300` |
| `MAX_TIME_LIMIT` | Maximum allowed time limit (seconds) | `600` | `1800` |
# 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"
}
```
### Claude Desktop Configuration
Add the following configuration to Claude Desktop's configuration file:
```json
{
"mcpServers": {
"file-operation-mcp": {
"url": "http://localhost:3000/sse"
}
}
}
```
### Cursor IDE Configuration
```json
{
"mcpServers": {
"file-operation-mcp": {
"url": "http://localhost:3000/sse"
}
}
}
```
### 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:**
```
Please count how many files are on my desktop
```
```
Please count the number of files in /Users/username/Documents folder
```
### 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:**
```
Please list all files on my desktop
```
```
Please show the contents of /Users/username/Downloads folder, including hidden files
```
### 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:**
```
Please compress /Users/username/Desktop/photo.jpg to 60% quality
```
```
Please compress image /path/to/image.png, limit max width to 1920 pixels
```
### 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:**
```
Please compress /Users/username/Documents folder to ZIP format
```
```
Please compress files ["/path/file1.txt", "/path/file2.txt"] to /backup/files.tar.gz format
```
```
Please compress the project folder into a high-compression ZIP package
```
### 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:**
```
Please extract /Downloads/archive.zip to /Projects/ directory
```
```
Please extract /backup/files.tar.gz to /restore/ and overwrite existing files
```
```
Please extract the archive to a temporary folder
```
**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:**
```
Please copy /Users/username/Documents/report.pdf to /backup/ directory
```
```
Please copy the entire project folder to a backup directory, preserving timestamps
```
```
Please copy the file and overwrite the existing target file
```
### 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:**
```
Please move /Downloads/archive.zip to /Projects/ directory
```
```
Please move the temporary folder to a permanent storage location
```
```
Please move the file and overwrite the same-named file at the target location
```
**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:**
```
Please merge these PDF files: ["/reports/report1.pdf", "/reports/report2.pdf"] to "/merged/combined_report.pdf"
```
```
Please merge project documents, set title to "Complete Project Documentation"
```
### 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:**
```
Please split "/documents/manual.pdf" by page to "/pages/" directory
```
```
Please split the PDF by ranges: ["1-5", "6-10", "11-15"]
```
```
Please split pages 3 to 8 of the PDF into separate files
```
- 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:**
```
Please convert "/docs/presentation.pdf" to PNG image, 300 DPI resolution
```
```
Please convert only pages 1, 3, and 5 of the PDF to JPEG images
```
```
Please convert PDF pages 10-20 to high-quality images
```
**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:**
```
Please create a new SQLite database /data/mydb.sqlite
```
```
Please execute query "SELECT * FROM users WHERE age > 18" in /data/mydb.sqlite database
```
```
Please import /data/users.csv into /data/mydb.sqlite database
```
```
Please backup /data/mydb.sqlite database to /backup/mydb_backup.sqlite
```
### 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:**
```
Please compress /Documents/ and /Projects/ directories to /backup/archive.zip
```
```
Please create /data/files.tar.gz archive with highest compression level
```
```
Please decompress /backup/archive.zip to /restore/ directory
```
```
Please test the integrity of /backup/archive.zip
```
### 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:**
```
Please sort /data/sorted.txt file in ascending order
```
```
Please remove duplicate lines from /logs/error.log
```
```
Please filter lines containing "ERROR" from /data/input.txt
```
```
Please merge /data/file1.txt and /data/file2.txt to /output/merged.txt
```
```
Please convert text in /data/input.txt to uppercase
```
## šø 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
```bash
pnpm dev
```
### Code Formatting
```bash
pnpm format
```
### Code Linting
```bash
pnpm lint
```
### Start Server
```bash
bun start # Now uses Bun for faster startup
```
## ā ļø 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**
```
Error: Cannot find module 'xxx'
```
**Solution**: Ensure `bun install` (or `pnpm install`) and `pnpm build` have been run.
**2. Permission Error**
```
Error: EACCES: permission denied
```
**Solution**: Check folder access permissions, or use a path with appropriate permissions.
**3. Path Does Not Exist**
```
Error: Path /xxx does not exist
```
**Solution**: Confirm the path is correct, use absolute paths.
**4. Unsupported Image Format**
```
Error: Unsupported image format .xxx
```
**Solution**: Use a supported image format (jpg, png, webp, tiff, gif).
**5. Archive Creation Failure**
```
Error: An error occurred while creating the archive
```
**Solution**:
- Check if file paths are correct
- Ensure write permissions for the output directory
- Check for sufficient disk space
**6. File Extraction Failure**
```
Error: Target directory is not empty
```
**Solution**: Set `overwrite=true` or clear the target directory.
**7. Unsupported Archive Format**
```
Error: Unsupported archive format
```
**Solution**: Use a supported format (.zip, .tar, .tar.gz, .tgz).
**8. File Copy Failure**
```
Error: Target path already exists
```
**Solution**: Set `overwrite=true` or choose a different target path.
**9. File Move Failure**
```
Error: Source path and target path cannot be the same
```
**Solution**: Ensure source and target paths are different.
**10. Insufficient Permissions**
```
Error: EACCES: permission denied
```
**Solution**:
- Check access permissions for source files and target directories
- Ensure sufficient disk space
- Avoid moving critical system files
**11. Corrupted PDF File**
```
Error: Unable to process 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**
```
Error: Batch conversion failed
```
**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**
```
Error: Page range out of valid bounds
```
**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](https://github.com/modelcontextprotocol/inspector) for debugging