File Operation Mcp

File Operation MCP Server

Model Context Protocol (MCP) に基づくファイル操作サーバーです。ファイル統計、一覧の取得、画像圧縮機能を提供します。

✨ 機能

• 📊 ファイル統計 - 指定したフォルダー内のファイル数を集計します
• 📋 ファイル一覧 - フォルダー内のすべてのファイルの詳細情報を取得します
• 🖼️ 画像圧縮 - 複数の形式に対応した高品質な画像圧縮
• 🗜️ ファイル圧縮 - ZIP、TAR、TAR.GZ形式の圧縮ファイルを作成します
• 📦 ファイル解凍 - ZIP、TAR、TAR.GZ形式の圧縮ファイルを解凍します
• 📂 ファイルコピー - ファイルまたはフォルダーを指定した場所にコピーします
• 🔄 ファイル移動 - ファイルまたはフォルダーを指定した場所に移動します
• 📄 PDF結合 - 複数のPDFファイルを1つに結合します
• ✂️ PDF分割 - PDFファイルをページ単位または範囲指定で分割します
• 🖼️ PDFから画像への変換 - PDFページをJPEG/PNG画像に変換します
• 🔒 安全性と信頼性 - 包括的なエラー処理とパラメーター検証
• ⚡ 高性能 - Node.jsとTypeScriptを基盤として構築されています

🛠️ 技術スタック

• TypeScript - 型安全なJavaScript
• MCP SDK - Model Context Protocol公式SDK
• Sharp - 高性能な画像処理ライブラリ
• PDF-lib - 結合と分割に対応した純粋なJavaScript PDF処理ライブラリ
• PDF2pic - PDFから画像への変換ツール
• Mammoth - Word文書処理ライブラリ
• Puppeteer - PDF生成に使用するヘッドレスブラウザー
• Archiver - ZIP、TARなどの形式に対応したファイル圧縮ライブラリ
• Extract-Zip - ZIPファイル解凍ライブラリ
• TAR - TAR形式ファイル処理ライブラリ
• fs-extra - 拡張ファイルシステム操作
• Zod - TypeScript優先のデータ検証

📦 インストール

必要条件

• Node.js >= 18.0.0
• pnpm（推奨）またはnpm

プロジェクトをクローン

git clone https://github.com/lxKylin/file-operation-mcp.git
cd file-operation-mcp

依存関係をインストール

pnpm install

プロジェクトをビルド

pnpm build

🔌 トランスポート方式の比較

このプロジェクトは2種類のMCPトランスポート方式に対応しています。利用シーンに応じて適切な方式を選択できます。

📊 StdioとSSEの比較表

特性	Stdio	SSE
トランスポートプロトコル	プロセス間通信（IPC）	HTTP/HTTPS
接続方式	stdin/stdout	Server-Sent Events
複数クライアントへの対応	❌ 1対1接続	✅ 複数対1の接続
リモートアクセス	❌ ローカルのみ	✅ リモートに対応
デプロイの複雑さ	✅ 簡単	❌ HTTPサーバーが必要
リソース使用量	✅ 少ない	❌ 比較的多い
デバッグのしやすさ	❌ 難しい	✅ 簡単（HTTPツール）
ネットワーク越え	❌ 非対応	✅ 対応
ロードバランシング	❌ 非対応	✅ 対応
監視機能	❌ 限定的	✅ 充実（ヘルスチェックなど）
遅延	✅ 非常に低い（約1～5ms）	❌ やや高い（約10～50ms）

🎯 おすすめの利用シーン

次の場合はStdioを選択してください：

• 🏠 ローカル開発: 個人向けのシンプルなデスクトップツール
• 🔒 単一ユーザー: 自分だけが使用するアプリケーション
• ⚡ 低遅延: 応答時間に非常に厳しい要件がある
• 📦 シンプルなデプロイ: HTTPサーバーを設定したくない
• 💾 リソースの節約: システムリソースが限られている

次の場合はSSEを選択してください：

• 🌐 リモートアクセス: ネットワーク経由でサーバーに接続する
• 👥 複数ユーザー: チームで共有するサーバー
• 🔄 高可用性: ロードバランシングとフェイルオーバーが必要
• 🐛 デバッグのしやすさ: 開発段階で使いやすいデバッグツールが必要
• 📈 拡張性: 将来的に水平スケーリングが必要になる可能性がある
• 🔍 監視要件: 詳細なサービス監視が必要

🔧 パフォーマンス比較

Stdioアーキテクチャ

客户端 ←→ 服务器进程 (直接IPC)
延迟: 1-5ms | 内存: 低 | CPU: 低

SSEアーキテクチャ

客户端 ←→ HTTP服务器 ←→ MCP服务器
延迟: 10-50ms | 内存: 中等 | CPU: 中等

🛠️ コードの違いの例

Stdioの起動方法

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const transport = new StdioServerTransport();
await server.connect(transport);
console.error('Stdio MCP服务器已启动');

SSEの起動方法

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服务器已启动在端口 3000');
});

💡 おすすめ: 個人ユーザーでローカル利用のみの場合は Stdio を選択してください。チームでの共同作業やリモートアクセスが必要な場合は SSE を選択してください。

---

⚙️ Stdioの設定

Claude Desktopの設定

以下の設定をClaude Desktopの設定ファイルに追加します。

設定ファイルの場所：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.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"
      }
    }
  }
}

⚠️ 注意: path/to/file-operation-mcp を実際のプロジェクトパスに置き換えてください。

Cursor IDEの設定

{
  "mcpServers": {
    "file-operation-mcp": {
      "command": "node",
      "args": ["path/to/file-operation-mcp/dist/index.js"]
    }
  }
}

⚙️ SSEの設定

SSEサーバーを起動

まずHTTPサーバーを起動します。

# 启动服务器
pnpm start
# 或
node dist/index.js

サーバーの起動後、次のように表示されます。

MCP文件操作服务器已启动在端口 3000
SSE端点: http://localhost:3000/sse
健康检查: http://localhost:3000/health

サーバーの状態を確認

# 检查服务器健康状态
curl http://localhost:3000/health

# 返回示例
{
  "status": "ok",
  "message": "MCP文件操作服务器运行中",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Claude Desktopの設定

以下の設定をClaude Desktopの設定ファイルに追加します。

{
  "mcpServers": {
    "file-operation-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Cursor IDEの設定

{
  "mcpServers": {
    "file-operation-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

SSEエンドポイントの説明

• SSE接続: http://localhost:3000/sse - 主要なMCP接続エンドポイント
• メッセージ処理: http://localhost:3000/messages - JSON-RPCメッセージを処理します
• ヘルスチェック: http://localhost:3000/health - サーバーの状態を確認します
• ポート設定: 環境変数 PORT で変更できます。デフォルトは3000です

⚠️ 注意: SSEモードでは、クライアントの接続を設定する前にサーバーを手動で起動する必要があります。

🚀 使用方法

設定が完了したらClaude Desktopを再起動すると、会話内で次の機能を使用できます。

1. ファイル統計（count-files）

指定したフォルダー内のファイル数を集計します。デフォルトではデスクトップ内のファイルを集計します。

パラメーター：

• folderPath（任意）: フォルダーのパス。デフォルトはデスクトップです

例：

请帮我统计一下桌面上有多少个文件

请统计 /Users/username/Documents 文件夹中的文件数量

2. ファイル一覧（list-files）

指定したフォルダー内のすべてのファイルについて、ファイル名、種類、サイズなどの詳細情報を取得します。

パラメーター：

• folderPath（任意）: フォルダーのパス。デフォルトはデスクトップです
• includeHidden（任意）: 隠しファイルを含めるかどうか。デフォルトはfalseです

例：

请列出桌面上的所有文件

请显示 /Users/username/Downloads 文件夹中的内容，包括隐藏文件

3. 画像圧縮（compress-image）

指定した画像ファイルを圧縮します。複数の形式とカスタムパラメーターに対応しています。

パラメーター：

• imagePath: 画像ファイルのパス（必須）
• quality（任意）: 圧縮品質（1～100）。デフォルトは80です
• maxWidth（任意）: 最大幅の上限
• maxHeight（任意）: 最大高さの上限
• outputPath（任意）: 出力先のパス。デフォルトでは元のファイル名に _compressed の接尾辞を付けます

対応形式：

• JPEG/JPG
• PNG
• WebP
• TIFF
• GIF

例：

请将 /Users/username/Desktop/photo.jpg 压缩到 60% 质量

请压缩图片 /path/to/image.png，限制最大宽度为 1920 像素

4. ファイルの圧縮 (create-archive)

ファイルまたはフォルダーをZIP、TAR、TAR.GZ形式に圧縮します。

パラメーター：

• files：圧縮するファイル／フォルダーのパスの配列（必須）
• outputPath：出力する圧縮ファイルのパス（必須）
• format（任意）：圧縮形式（zip、tar、tar.gz）。既定値はzipです
• compressionLevel（任意）：圧縮レベル（0～9）。既定値は6です

対応形式：

• ZIP - 汎用圧縮形式で、最も互換性があります
• TAR - Unix/Linuxで一般的な形式で、圧縮は行いません
• TAR.GZ - TAR形式をGZIPで圧縮した形式で、圧縮率が高いです

例：

请将 /Users/username/Documents 文件夹压缩为ZIP格式

请压缩文件 ["/path/file1.txt", "/path/file2.txt"] 为 /backup/files.tar.gz 格式

请将项目文件夹压缩为高压缩级别的ZIP包

5. ファイルの展開 (extract-archive)

ZIP、TAR、TAR.GZファイルを指定したディレクトリに展開します。

パラメーター：

• archivePath：圧縮ファイルのパス（必須）
• extractTo：展開先ディレクトリ（必須）
• overwrite（任意）：既存のファイルを上書きするかどうか。既定値はfalseです

対応形式：

• ZIP - .zipファイル
• TAR - .tarファイル
• TAR.GZ - .tar.gz、.tgzファイル

例：

请解压 /Downloads/archive.zip 到 /Projects/ 目录

请解压 /backup/files.tar.gz 到 /restore/ 并覆盖现有文件

请将压缩包解压到临时文件夹

注意事項：

• 展開前に、対象ディレクトリが空かどうかを確認します（overwrite=trueに設定した場合を除く）
• 圧縮形式を自動検出します
• 展開したファイル数と合計サイズを表示します
• 展開中は元のファイル構造を維持します

6. ファイルのコピー (copy-files)

元のファイルを変更せずに、ファイルまたはフォルダーを指定した場所にコピーします。

パラメーター：

• sourcePath：コピー元のファイル／フォルダーのパス（必須）
• targetPath：コピー先のパス（必須）
• overwrite（任意）：既存のファイルを上書きするかどうか。既定値はfalseです
• preserveTimestamps（任意）：タイムスタンプを保持するかどうか。既定値はtrueです

機能：

• ファイルとフォルダーのコピーに対応
• ディレクトリ構造全体を再帰的にコピー
• 元のタイムスタンプを保持するかどうかを選択可能
• 誤って上書きしないよう安全性を確認
• コピーの詳細とファイル統計を表示

例：

请复制 /Users/username/Documents/report.pdf 到 /backup/ 目录

请复制整个项目文件夹到备份目录，保留时间戳

请复制文件并覆盖已存在的目标文件

7. ファイルの移動 (move-files)

ファイルまたはフォルダーを指定した場所に移動します。切り取り操作に相当します。

パラメーター：

• sourcePath：移動元のファイル／フォルダーのパス（必須）
• targetPath：移動先のパス（必須）
• overwrite（任意）：既存のファイルを上書きするかどうか。既定値はfalseです

機能：

• ファイルとフォルダーの移動に対応
• データの安全性を確保するアトミック操作
• 移動の完了を自動的に確認
• 移動元と移動先のパスが同じ場合に処理を防止
• ファイルシステムをまたいだ移動に対応

例：

请移动 /Downloads/archive.zip 到 /Projects/ 目录

请将临时文件夹移动到永久存储位置

请移动文件并覆盖目标位置的同名文件

注意事項：

• 移動操作により、元のファイル／フォルダーは削除されます
• パーティション／ドライブをまたいだ移動に対応
• 移動前に対象ディレクトリのアクセス権限を確認します
• 操作完了後に結果を確認します

8. PDFの結合 (merge-pdf)

複数のPDFファイルを1つの完全なPDFドキュメントに結合します。

パラメーター：

• inputPaths：PDFファイルのパスの配列（必須）
• outputPath：出力するPDFファイルのパス（必須）
• title（任意）：結合後のPDFのタイトル

機能：

• 任意の数のPDFファイルの結合に対応
• 元のページ形式と品質を維持
• ドキュメントのメタデータを自動設定
• 詳細な結合統計レポート
• .pdf拡張子を自動的に追加

例：

请合并这些PDF文件：["/reports/report1.pdf", "/reports/report2.pdf"] 到 "/merged/combined_report.pdf"

请将项目文档合并，标题设为 "完整项目文档"

9. PDFの分割 (split-pdf)

PDFファイルを複数の独立したファイルに分割します。ページ単位またはカスタム範囲での分割に対応します。

パラメーター：

• inputPath：入力するPDFファイルのパス（必須）
• outputDir：出力先ディレクトリ（必須）
• splitMode（任意）：分割モード - pages（1ページごとに1ファイル）またはranges（範囲ごとに分割）。既定値はpagesです
• ranges（任意）：ページ範囲の配列。例：["1-3", "4-6"]。rangesモードでのみ必要です
• prefix（任意）：出力ファイル名のプレフィックス。既定値は元のファイル名です

機能：

• 2つの分割モード：ページごとの分割または範囲ごとの分割
• 柔軟なページ範囲の指定
• 元のページ形式を維持
• ファイル名と番号を自動設定
• 詳細な分割統計

例：

请将 "/documents/manual.pdf" 按页面拆分到 "/pages/" 目录

请将PDF按范围拆分：["1-5", "6-10", "11-15"]

请拆分PDF的第3页到第8页为单独文件

• 分割前

• 分割後

10. PDFから画像への変換 (pdf-to-image)

PDFのページを高品質な画像ファイルに変換します。複数の形式とカスタム設定に対応します。

パラメーター：

• inputPath：入力するPDFファイルのパス（必須）
• outputDir：出力先ディレクトリ（必須）
• format（任意）：画像形式 - jpegまたはpng。既定値はjpegです
• quality（任意）：画像品質（1～100）。既定値は80です
• dpi（任意）：解像度DPI（50～600）。既定値は150です
• pages（任意）：ページ範囲。例："1-3"または"1,3,5"。既定値は全ページです
• prefix（任意）：出力ファイル名のプレフィックス

機能：

• JPEGとPNG形式に対応
• 画像品質と解像度を調整可能
• 柔軟なページ選択（範囲、リスト、単一ページ）
• すべてのページを一括処理
• 詳細な変換統計情報

例：

请将 "/docs/presentation.pdf" 转换为PNG图片，分辨率300 DPI

请只转换PDF的第1、3、5页为JPEG图片

请将PDF第10-20页转换为高质量图片

注意事項：

• PDFから画像への変換には、システムでImageMagickまたはGraphicsMagickがサポートされている必要があります
• 高解像度に設定すると、ファイルサイズと処理時間が増加します
• PNG形式はファイルサイズが大きくなりますが、品質はより高くなります
• 推奨解像度：画面表示は150 DPI、印刷は300 DPI

📸 機能デモ

ファイル一覧の取得

既定ではデスクトップ上のファイルを取得します。パスを指定することもできます：

ファイル数の集計

指定したディレクトリ内のファイル数をすばやく集計します：

画像の圧縮機能

カスタムパラメーターに対応した高品質な画像圧縮：

🔧 開発

開発モード

pnpm dev

コードのフォーマット

pnpm format

コードのチェック

pnpm lint

サーバーの起動

pnpm start

⚠️ 注意事項

1. 権限要件：Node.jsが対象フォルダーにアクセスできることを確認してください
2. パスの形式：
   • macOS/Linux：/Users/username/path
   • Windows：C:\Users\username\path
3. 画像形式：一般的な画像形式（JPEG、PNG、WebP、TIFF、GIF）のみサポートしています
4. 圧縮形式：ZIP、TAR、TAR.GZ形式での圧縮と展開に対応しています
5. ファイル操作：ファイルとフォルダーのコピーおよび移動に対応しています
6. PDF処理：PDFの結合、分割、画像への変換機能はすべて純粋なJavaScriptで実装されています
7. 画像変換：PDFから画像への変換には、システムでImageMagickまたはGraphicsMagickがサポートされている必要があります
8. ファイル権限：元のファイルと対象ディレクトリに適切な権限があることを確認してください
9. 上書き保護：既定では既存のファイルを上書きしません。上書きするには明示的な設定が必要です
10. ファイルサイズ：大きなファイルの処理には、より長い時間がかかる場合があります
11. デバッグ出力：MCPプロトコルへの干渉を避けるため、console.log()ではなくconsole.error()を使用してください

🐛 トラブルシューティング

よくある質問

1. サーバーの起動に失敗する

Error: Cannot find module 'xxx'

解決策: pnpm install と pnpm build を実行したことを確認してください。

2. 権限エラー

Error: EACCES: permission denied

解決策: フォルダーのアクセス権を確認するか、適切な権限があるパスを使用してください。

3. パスが存在しない

错误：路径 /xxx 不存在

解決策: パスが正しいことを確認し、絶対パスを使用してください。

4. 画像形式がサポートされていない

错误：不支持的图片格式 .xxx

解決策: サポートされている画像形式（jpg、png、webp、tiff、gif）を使用してください。

5. 圧縮ファイルの作成に失敗する

错误：创建压缩文件时发生错误

解決策:

• ファイルパスが正しいか確認してください。
• 出力ディレクトリへの書き込み権限があることを確認してください。
• ディスクの空き容量が十分か確認してください。

6. ファイルの展開に失敗する

错误：目标目录不为空

解決策: overwrite=true を設定するか、対象ディレクトリを空にしてください。

7. サポートされていない圧縮形式

错误：不支持的压缩格式

解決策: サポートされている形式（.zip、.tar、.tar.gz、.tgz）を使用してください。

8. ファイルのコピーに失敗する

错误：目标路径已存在

解決策: overwrite=true を設定するか、別の保存先パスを選択してください。

9. ファイルの移動に失敗する

错误：源路径和目标路径不能相同

解決策: コピー元のパスと保存先のパスが異なることを確認してください。

10. 権限が不足している

Error: EACCES: permission denied

解決策:

• コピー元ファイルと対象ディレクトリのアクセス権を確認してください。
• ディスクの空き容量が十分にあることを確認してください。
• システムの重要なファイルの移動は避けてください。

11. PDFファイルが破損している

错误：无法处理PDF文件

解決策:

• PDFファイルが完全で、破損していないことを確認してください。
• PDFファイルがパスワードで保護されていないことを確認してください。
• 別のPDFビューアーでファイルを検証してみてください。

12. PDFから画像への変換に失敗する

错误：批量转换失败

解決策:

• システムにImageMagickまたはGraphicsMagickがインストールされていることを確認してください。
• システムのPATH環境変数の設定を確認してください。
• DPIの設定を下げるか、ページ数を減らしてください。

13. ページ範囲エラー

错误：页面范围超出有效范围

解決策:

• PDFファイルの実際のページ数を確認してください。
• ページ範囲の形式が正しいことを確認してください（例：「1-5」、「1,3,5」）。
• ページ番号は0ではなく、1から始まります。

デバッグのヒント

1. Claude Desktop の開発者コンソールを確認します。
2. サーバーのログ出力を確認します。
3. MCP Inspector を使用してデバッグします。