File Operation

You have a Model Context Protocol (MCP) based File Operation Server that exposes a rich set of file and PDF utilities through a fast, typed interface. You can query file statistics, list directory contents, compress and extract archives, manipulate PDFs, convert PDFs to images, and perform various file operations like copy and move—all from MCP-compatible clients. This guide walks you through practical usage, installation steps, configuration, and common considerations so you can start integrating and automating your workflows right away.

How to use

Learn how to perform common tasks with MCP clients that connect to the File Operation Server. You can count files, list files in a directory, compress or extract archives, merge or split PDFs, convert PDF pages to images, and execute a wide range of file utilities. Once the MCP client is connected, you’ll issue high-level actions (such as count-files, list-files, compress-image, create-archive, extract-archive, copy-files, move-files, merge-pdf, split-pdf, pdf-to-image, query-sqlite, compress-files, process-text) and receive structured results without dealing with low-level file system calls.

A reliable setup lets you operate locally through Stdio (for single-user, low-latency scenarios) or remotely via SSE (for multi-user or networked access). Use Stdio if you’re developing locally with minimal infrastructure. Use SSE when you need remote access, monitoring, and potential horizontal scaling.

How to install

Prerequisites you need before starting: a modern runtime and package tooling, plus a compatible OS environment.

1. Install prerequisites and tools:

2. Install Bun for running the server and optimize startup performance.

3. Install dependencies and build the project.

pnpm install
bun install # Alternative if Bun is preferred

pnpm build
# Once built, you can start the server in the next step

HTTP MCP server configuration

The server exposes an HTTP MCP endpoint you can connect to from any MCP-compatible client over the network. The MCP endpoint is served at an HTTP interface and the health check endpoint reports runtime status.

Connection details you’ll use from the client side include the primary MSSP endpoint and a health route for monitoring.

URL: http://localhost:3000/sse
Health: http://localhost:3000/health

STDIO MCP server configuration (local startup example)

If you run the server locally as a standard process, you can connect via a standard input/output transport. Use the following command to start the MCP server locally.

{
  "name": "file_operation_mcp",
  "type": "stdio",
  "command": "node",
  "args": ["path/to/file-operation-mcp/dist/index.js"],
  "cwd": "path/to/file-operation-mcp",
  "env": {
    "NODE_ENV": "production"
  }
}

Security, configuration, and notes

• Set appropriate file system permissions for source and target directories to avoid unauthorized access or data loss. - By default, existing files are not overwritten unless you explicitly enable overwrite in the operation options. - Ensure system dependencies for image and PDF processing (like ImageMagick/GraphicsMagick for PDF to image) are installed if you plan to use those features.

Troubleshooting

Common issues include startup failures, permission errors, path misconfigurations, or missing dependencies. Check that dependencies are installed, the server binaries are built, and that the paths you provide exist and are accessible.

Examples of supported operations

The server provides a suite of operations you can invoke via MCP clients. Examples include counting files in a directory, listing files with details, compressing images, creating archives, extracting archives, copying and moving files, merging or splitting PDFs, converting PDFs to images, and performing SQLite operations. Each operation accepts clearly defined parameters and returns structured results.

Development and run commands

To run in development mode, you typically start the server with your package manager and the Bun runtime for speed. Use the following commands to run and test locally.

pnpm dev

bun start

Available tools

count-files

Counts the number of files in a specified directory and returns the total.

list-files

Lists detailed information for all files in a directory, including name, type, size, and timestamps.

compress-image

Compresses image files with configurable quality and dimensions across formats like JPEG, PNG, WebP, TIFF, and GIF.

create-archive

Archives a set of files or directories into ZIP, TAR, or TAR.GZ formats with configurable compression.

extract-archive

Extracts ZIP, TAR, or TAR.GZ archives into a target directory, preserving structure.

copy-files

Copies files or folders to a target location, preserving original files and optionally timestamps.

move-files

Moves files or folders to a target location with optional overwrite and integrity checks.

merge-pdf

Merges multiple PDF files into a single document with metadata handling.

split-pdf

Splits a PDF by pages or by specified ranges into separate output files.

pdf-to-image

Converts PDF pages to image files (JPEG/PNG) with control over format, quality, and DPI.

query-sqlite

Performs SQLite operations including create, query execution, CSV import/export, and schema info.

compress-files

Compresses or decompresses various formats (ZIP, TAR, GZIP, BZIP2) with options for password, patterns, and validation.

process-text

Provides text processing utilities such as sort, dedupe, filter, replace, count, and case transformation.