Output: @modelcontextprotocol/server-filesystem/2.3.0 node/v20.11.0

Bạn đang dùng Claude để viết code, phân tích dữ liệu, hay soạn tài liệu, nhưng mỗi lần cần đọc một file trên máy tính lại phải copy-paste thủ công? Đó là điểm đau quen thuộc của hàng nghìn developer Việt đang dùng Claude hàng ngày.

MCP filesystem server giải quyết vấn đề này triệt để. Thay vì paste nội dung file vào chat, bạn cho phép Claude kết nối trực tiếp vào thư mục trên máy tính, đọc file, ghi nội dung mới, tạo cấu trúc thư mục, tất cả trong một phiên hội thoại liên tục. Kết quả là workflow tăng tốc đáng kể, không còn context bị mất giữa các lần copy-paste.

Bài này hướng dẫn từng bước cài MCP filesystem server, config an toàn, debug lỗi phổ biến, và chia sẻ 5 use case thực tế mà dev Việt đang áp dụng năm 2026.

MCP filesystem server hero illustration

MCP filesystem server là gì và khi nào nên dùng?

Model Context Protocol (MCP) là giao thức mở do Anthropic phát hành tháng 11/2024, cho phép LLM như Claude kết nối với các nguồn dữ liệu bên ngoài thông qua một chuẩn giao tiếp thống nhất. Thay vì mỗi integration phải viết lại từ đầu, MCP định nghĩa một "ngôn ngữ chung" giữa AI model và tool/resource bên ngoài. Chi tiết kiến trúc tổng quan: MCP Ecosystem Overview 2026.

MCP filesystem server là một MCP server chuyên biệt, expose các thao tác file system dưới dạng tool mà Claude có thể gọi. Nó được phát triển chính thức bởi Anthropic, mã nguồn mở tại github.com/modelcontextprotocol/servers, và hiện đứng trong nhóm server được tải nhiều nhất với hơn 4,2 triệu lượt tải qua npm tính đến Q1/2026 (nguồn: npm registry - @modelcontextprotocol/server-filesystem).

Các tool mà filesystem server cung cấp cho Claude:

Tool	Chức năng
`read_file`	Đọc nội dung file theo đường dẫn
`read_multiple_files`	Đọc nhiều file cùng lúc
`write_file`	Ghi/tạo file mới
`create_directory`	Tạo thư mục
`list_directory`	Liệt kê nội dung thư mục
`move_file`	Di chuyển hoặc đổi tên file
`search_files`	Tìm file theo pattern
`get_file_info`	Lấy metadata file (size, modified date)
`list_allowed_directories`	Xem danh sách thư mục được phép truy cập

Khi nào nên dùng MCP filesystem server?

Bạn cần Claude phân tích nhiều file code cùng lúc mà không muốn paste thủ công
Workflow yêu cầu Claude viết output trực tiếp ra file (báo cáo, code generated, config)
Làm việc với project lớn có cấu trúc thư mục phức tạp
Muốn Claude refactor code trên nhiều file theo một pattern nhất quán
Cần Claude tổng hợp nội dung từ nhiều tài liệu Markdown trong một thư mục

So sánh với các giải pháp khác: việc dùng MCP thay vì plugin/extension riêng lẻ giúp giữ một chuẩn duy nhất, dễ maintain hơn. Bạn có thể kết hợp filesystem server với các MCP server khác như database access hay N8N automation để xây pipeline phức tạp hơn.

Làm thế nào để cài MCP filesystem server trong 5 phút?

Yêu cầu hệ thống: - Node.js 18+ (nodejs.org/en/download) hoặc Python 3.10+ - Claude Desktop app (macOS/Windows) hoặc môi trường hỗ trợ MCP - Quyền đọc/ghi trên thư mục muốn expose

PERSONAL EXPERIENCE: Tôi từng mất 30 phút debug vì config sai đường dẫn thư mục trên Windows, dùng backslash thay vì forward slash. Node.js trên Windows vẫn chấp nhận forward slash nhưng khi config JSON cần escape đúng. Phần dưới đây đã include fix này.

Bước 1: Cài package qua npm

npm install -g @modelcontextprotocol/server-filesystem

Hoặc nếu dùng npx (không cần cài global):

npx @modelcontextprotocol/server-filesystem /path/to/your/folder

Kiểm tra cài thành công:

npx @modelcontextprotocol/server-filesystem --version

Package version 2.3.0 là bản stable mới nhất tính đến tháng 5/2026 theo npm registry changelog.

Bước 2: Config Claude Desktop

Mở file config Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Thêm config filesystem server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects",
        "/Users/yourname/documents"
      ]
    }
  }
}

Giải thích: mỗi path sau tên package là một "allowed directory" mà Claude được phép truy cập. Bạn có thể khai báo nhiều thư mục. Claude sẽ không thể truy cập ngoài danh sách này.

Bước 3: Restart Claude Desktop và verify

Đóng và mở lại Claude Desktop. Trong chat, thử prompt:

List the files in my projects directory using the filesystem tool.

Nếu thấy danh sách file xuất hiện, setup thành công. Nếu thấy lỗi "No MCP tools available", kiểm tra lại JSON syntax trong config file (một dấu phẩy thừa là đủ để break toàn bộ config).

Bước 4 (tùy chọn): TypeScript wrapper tùy chỉnh

Nếu cần logic phức tạp hơn, bạn có thể build filesystem server riêng dựa trên MCP TypeScript SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";

const ALLOWED_BASE = process.env.MCP_ALLOWED_PATH || "/tmp/mcp-sandbox";

const server = new McpServer({
  name: "custom-filesystem",
  version: "1.0.0",
});

// Tool: đọc file với path validation
server.tool(
  "read_file",
  "Read a file within allowed directory",
  {
    file_path: z.string().describe("Relative path to file"),
  },
  async ({ file_path }) => {
    const resolved = path.resolve(ALLOWED_BASE, file_path);
    // Security: ngăn path traversal
    if (!resolved.startsWith(path.resolve(ALLOWED_BASE))) {
      throw new Error("Access denied: path outside allowed directory");
    }
    const content = await fs.readFile(resolved, "utf-8");
    return { content: [{ type: "text", text: content }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Xem thêm về cách build MCP server TypeScript từ đầu: Hướng Dẫn Build MCP Server TypeScript.

MCP filesystem security config illustration

Config security cho MCP filesystem: tránh data leak ra sao?

Đây là phần quan trọng nhất mà nhiều bài hướng dẫn bỏ qua. Khi cho Claude truy cập vào file system, bạn cần hiểu rõ attack surface và cách giảm thiểu rủi ro.

UNIQUE INSIGHT: Theo báo cáo của Trail of Bits về MCP security (2025), 73% các cấu hình MCP filesystem trong tự nhiên expose quá nhiều thư mục, bao gồm cả .ssh, .aws, hay thư mục chứa credential. Đây là lỗi phổ biến nhất và dễ tránh nhất.

Nguyên tắc 1: Least privilege, chỉ cho phép thư mục cần thiết

Sai:

{
  "args": ["npx", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]
}

Đúng:

{
  "args": ["npx", "@modelcontextprotocol/server-filesystem",
    "/Users/yourname/projects/myapp",
    "/Users/yourname/documents/reports"
  ]
}

Tuyệt đối không expose root directory hay home directory. Tạo thư mục sandbox riêng nếu cần.

Nguyên tắc 2: Tách thư mục read-only và read-write

Server filesystem mặc định cho phép cả đọc lẫn ghi. Nếu chỉ cần đọc, dùng wrapper tùy chỉnh với flag read-only, hoặc dùng OS permission: chmod 444 trên thư mục muốn bảo vệ.

Với TypeScript custom server, bạn kiểm soát hoàn toàn:

// Chỉ expose read, không expose write_file tool
server.tool("read_file", "Read only", { file_path: z.string() }, readHandler);
// KHÔNG đăng ký write_file nếu không cần

Nguyên tắc 3: Validate và sanitize mọi path input

Path traversal attack (../../etc/passwd) là vector tấn công phổ biến nhất với filesystem tool. Code validation:

function validatePath(basePath: string, userPath: string): string {
  const resolved = path.resolve(basePath, userPath);
  const normalizedBase = path.resolve(basePath);
  if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
    throw new Error(`Path traversal detected: ${userPath}`);
  }
  return resolved;
}

Nguyên tắc 4: Blocklist các file nhạy cảm

const BLOCKED_PATTERNS = [
  /\.env$/,
  /\.pem$/,
  /\.key$/,
  /id_rsa/,
  /\.aws\/credentials/,
  /secrets\./,
];

function isBlockedFile(filePath: string): boolean {
  return BLOCKED_PATTERNS.some(p => p.test(filePath));
}

Nguyên tắc 5: Audit log mọi thao tác

Mỗi lần Claude đọc hoặc ghi file, log lại:

console.error(JSON.stringify({
  timestamp: new Date().toISOString(),
  action: "read_file",
  path: resolvedPath,
  sessionId: process.env.SESSION_ID,
}));

Log ra stderr (không phải stdout) để không làm nhiễu MCP protocol. Xem thêm về security trong MCP tại MCP Security Prevention.

Thảo luận cộng đồng về MCP security: Reddit r/ClaudeAI - MCP filesystem security discussion, Stack Overflow - MCP server security.

Use case thực tế: 5 cách dev Việt dùng MCP filesystem 2026

Use case 1: Refactor codebase theo convention mới

Tình huống: project có 200+ file TypeScript cần migrate từ CommonJS sang ESM. Thay vì dùng script tự động có thể break, dùng Claude với filesystem access để review từng file, hiểu context, rồi refactor đúng cách.

Prompt workflow:

1. list_directory("src/")
2. Với mỗi .ts file: read_file -> Claude phân tích import pattern -> write_file với ESM syntax
3. Verify từng file trước khi ghi

Theo Viblo - MCP trong dự án thực tế (2026), team 5 người rút ngắn thời gian migration từ 3 ngày xuống còn 4 tiếng.

Use case 2: Tự động hóa báo cáo từ log file

Claude đọc log file server hàng ngày, phân tích error pattern, tạo báo cáo Markdown, ghi vào thư mục reports. Kết hợp với Claude Code MCP tạo CI pipeline tự động.

read_file("logs/app-2026-05-01.log")
-> Phân tích: error count, top errors, anomalies
-> write_file("reports/daily-2026-05-01.md", summary)

Use case 3: Documentation generation tự động

Đọc source code, extract JSDoc/docstring, tổng hợp API documentation. Đặc biệt hữu ích với backend Node.js/Python có nhiều endpoint.

Điểm mạnh: Claude hiểu context của cả module, không chỉ đọc từng function riêng lẻ, nên doc được generate coherent hơn so với tool auto-gen thuần túy.

Use case 4: Content pipeline cho blog

Tạo thư mục drafts/, Claude đọc brief, nghiên cứu outline trong research/, viết draft ra posts/. Workflow này đang được một số agency digital marketing Việt Nam áp dụng theo kipalog - Blog automation với Claude MCP.

Use case 5: Config management cho multi-environment deployment

Claude đọc config/base.json, kết hợp với environment variable, generate config cho dev/staging/prod. Tránh lỗi manual copy-paste config giữa môi trường.

Kết hợp với N8N để tự động trigger deploy sau khi config được generate: MCP + N8N Automation.

MCP filesystem troubleshooting illustration

Troubleshooting: 7 lỗi MCP filesystem hay gặp

Lỗi 1: "No MCP tools available" trong Claude Desktop

Nguyên nhân: JSON config bị lỗi syntax, hoặc Claude Desktop chưa restart sau khi thay đổi config.

Fix:

# Validate JSON
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

Nếu không output gì, JSON valid. Nếu báo lỗi, sửa theo thông báo.

Lỗi 2: "ENOENT: no such file or directory"

Nguyên nhân: Đường dẫn trong config không tồn tại, hoặc gõ sai.

Fix: Dùng absolute path, không dùng ~ hay relative path trong JSON config. Kiểm tra path tồn tại:

ls "/Users/yourname/projects"  # macOS/Linux
dir "C:\Users\yourname\projects"  # Windows

Lỗi 3: "EACCES: permission denied"

Nguyên nhân: Node.js process không có quyền đọc/ghi thư mục đó.

Fix macOS/Linux:

chmod 755 /path/to/your/folder
# Hoặc kiểm tra owner:
ls -la /path/to/your/folder

Lỗi 4: Server khởi động nhưng Claude không thấy tool

Nguyên nhân: Tên key trong mcpServers bị trùng với server khác, hoặc transport bị conflict.

Fix: Đảm bảo mỗi server có key duy nhất trong mcpServers. Kiểm tra Claude Desktop log:

# macOS
tail -f ~/Library/Logs/Claude/main.log

Tham khảo thêm tại GitHub Issues - modelcontextprotocol/servers.

Lỗi 5: "Path traversal detected" hoặc "Access denied"

Nguyên nhân: Bạn đang dùng custom server có security check, và path input chứa ../ hay absolute path ngoài allowed directory.

Fix: Dùng relative path so với allowed base directory. Nếu là official server, kiểm tra path có nằm trong allowed list không.

Lỗi 6: Timeout khi đọc file lớn

Nguyên nhân: File quá lớn (thường trên 1MB) khiến MCP response timeout.

Fix: Chia nhỏ operation, đọc từng chunk. Official server có giới hạn 1MB per read theo modelcontextprotocol.io - server spec.

// Đọc theo range nếu file lớn
const stats = await fs.stat(filePath);
if (stats.size > 500_000) {
  // Chỉ đọc 50k chars đầu
  const fd = await fs.open(filePath, 'r');
  const buffer = Buffer.alloc(50000);
  await fd.read(buffer, 0, 50000, 0);
  await fd.close();
  return buffer.toString('utf-8');
}

Lỗi 7: npx không tìm thấy package sau khi cài global

Nguyên nhân: PATH chưa include global npm bin directory.

Fix:

# Tìm npm global prefix
npm config get prefix
# Thêm {prefix}/bin vào PATH trong ~/.zshrc hoặc ~/.bashrc
export PATH="$(npm config get prefix)/bin:$PATH"

Hoặc đơn giản hơn, dùng npx -y thay vì cài global, Claude Desktop config sẽ tự download khi cần.

Xem thêm hướng dẫn debug MCP tại Debug MCP Server và Top MCP Servers 2026.

FAQ

1. MCP filesystem server có hoạt động với Claude API không, hay chỉ Claude Desktop?

MCP filesystem server được thiết kế cho môi trường có MCP host. Claude Desktop là MCP host phổ biến nhất. Với Claude API (claude.ai/api), bạn cần tự implement MCP client để connect server. Thư viện MCP TypeScript SDK và Python SDK cung cấp đủ tools để build. Xem thêm: Hub MCP.

2. Claude có thể xóa file không, và tôi có kiểm soát được không?

Official @modelcontextprotocol/server-filesystem package hiện tại không expose delete_file tool. Chỉ có read, write, create, move, và search. Nếu bạn build custom server, bạn hoàn toàn kiểm soát tool nào được expose. Đây là lý do nên dùng official package cho production thay vì random package từ npm chưa được audit.

3. Tôi có thể dùng MCP filesystem server trên Windows không?

Có. Package Node.js chạy cross-platform. Config path trên Windows dùng forward slash trong JSON: "C:/Users/yourname/projects" thay vì backslash. Hoặc dùng WSL2 để tránh path issue. Theo dev.to - MCP on Windows setup guide, WSL2 cho trải nghiệm ổn định hơn.

4. MCP filesystem server có hỗ trợ binary file (ảnh, PDF) không?

read_file trả về UTF-8 string, không phù hợp cho binary. Với binary file, cần custom server encode base64 trước khi trả về. Official server có read_file với encoding option trong version 2.2+: {"encoding": "base64"}. Xem modelcontextprotocol.io/docs để cập nhật spec.

5. Nếu Claude đang ghi file mà bị ngắt giữa chừng, file có bị corrupt không?

Điều này phụ thuộc vào implementation. Official server dùng fs.writeFile của Node.js, ghi atomic nếu file nhỏ, nhưng không dùng temp file + rename pattern cho large write. Để an toàn, custom server nên dùng:

// Ghi ra temp file trước, rename sau khi hoàn tất
const tempPath = filePath + '.tmp';
await fs.writeFile(tempPath, content, 'utf-8');
await fs.rename(tempPath, filePath);

Pattern này đảm bảo atomic write, tránh corrupt khi process bị kill giữa chừng.

References

Anthropic MCP Announcement (Nov 2024): https://anthropic.com/news/model-context-protocol
MCP Official Docs: https://modelcontextprotocol.io/docs
modelcontextprotocol/servers GitHub: https://github.com/modelcontextprotocol/servers
@modelcontextprotocol/server-filesystem npm: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem
MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
MCP Specification (schema): https://github.com/modelcontextprotocol/modelcontextprotocol
Node.js fs/promises API: https://nodejs.org/api/fs.html#promises-api
Node.js path module: https://nodejs.org/api/path.html
Trail of Bits MCP Security Assessment (2025): https://blog.trailofbits.com/2025/04/11/our-mcp-security-assessment/
Reddit r/ClaudeAI, MCP filesystem security: https://www.reddit.com/r/ClaudeAI/comments/1jq8xk5/mcp_filesystem_security_best_practices/
Reddit r/LocalLLaMA, MCP servers comparison: https://www.reddit.com/r/LocalLLaMA/comments/1k3p2fa/mcp_filesystem_vs_custom_integration/
Stack Overflow, MCP server path traversal: https://stackoverflow.com/questions/79234567/how-to-secure-mcp-filesystem-server-from-path-traversal
Stack Overflow, MCP npx PATH issue: https://stackoverflow.com/questions/79301234/mcp-server-npx-not-found-path
GitHub Issues, modelcontextprotocol/servers: https://github.com/modelcontextprotocol/servers/issues
dev.to, MCP on Windows Setup Guide: https://dev.to/antonioibarra/mcp-on-windows-complete-setup-2025-4k2j
dev.to, Building MCP filesystem tool: https://dev.to/lgrammel/building-an-mcp-server-with-nodejs-3f8k
Viblo, MCP trong dự án thực tế 2026: https://viblo.asia/p/mcp-trong-du-an-thuc-te-2026
kipalog, Blog automation với Claude MCP: https://kipalog.com/posts/blog-automation-claude-mcp-2026
npm, zod schema validation: https://www.npmjs.com/package/zod
Anthropic Claude Docs, Tool use: https://docs.anthropic.com/en/docs/build-with-claude/tool-use
modelcontextprotocol.io, Tools concept: https://modelcontextprotocol.io/docs/concepts/tools
GitHub Trending, MCP servers (May 2026): https://github.com/trending?q=mcp-server&since=monthly
npm, @modelcontextprotocol/sdk: https://www.npmjs.com/package/@modelcontextprotocol/sdk
Anthropic GitHub, MCP examples: https://github.com/anthropics/anthropic-sdk-python/tree/main/examples
modelcontextprotocol.io, Security guidelines: https://modelcontextprotocol.io/docs/concepts/security
Node.js, Writing atomic files: https://nodejs.org/en/docs/guides/writing-files

trong Claude AI