Local Filesystem MCP Server (maic-server-fs-mcp)

一个基于 Model Context Protocol (MCP) 构建的自定义本地文件系统与命令行执行服务。此工具已被发布至 NPM，支持通过 npx 直接在 LLM 客户端（如 Cursor、Claude Desktop 等）中无缝运行。

🛠️ 核心工具 (Tools)

本 MCP 服务端向 LLM 提供了以下接口能力：

Related MCP server: MCP Filesystem Server

🔌 接入与集成当前 MCP 服务

您可以通过 NPM 方式直接运行（推荐），或者使用本地克隆源码开发模式。

方式 1: 通过 NPM 接入（最简便，推荐）

A. 接入 Cursor 编辑器

1. 打开 Cursor 设置：进入 Settings ➡️ Features ➡️ MCP。

2. 点击 + Add New MCP Server：

   • Name: maic-local-filesystem-mcp

   • Type: command

   • Command:

     npx -y --package maic-server-fs-mcp mcp-server-fs

3. 点击 Save。等待状态指示灯亮起绿色 🟢。

B. 接入 Claude Desktop

1. 打开并编辑 Claude Desktop 的配置文件：

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

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

2. 在 mcpServers 节点内，追加如下配置：

   {
     "mcpServers": {
       "maic-local-filesystem-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "--package",
           "maic-server-fs-mcp",
           "mcp-server-fs"
         ]
       }
     }
   }

3. 保存文件并重启 Claude Desktop。

方式 2: 使用本地克隆源码运行（适合贡献者/二次开发）

1. 安装与构建

git clone https://github.com/maicFir/server-fs-mcp.git
cd server-fs-mcp
npm install
npm run build # 编译生成 dist/server.js

2. 在客户端中配置本地路径

• Cursor (Command):

  node /absolute/path/to/server-fs-mcp/dist/server.js

• Claude Desktop (claude_desktop_config.json):

  "maic-local-filesystem-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/server-fs-mcp/dist/server.js"
    ]
  }

⚠️ 开发者必看避坑指南 (Gotchas)

• 标准输出占用：MCP 的 stdio 传输机制完全独占了标准输出流 (stdout) 用于 JSON-RPC 通信。因此在开发调试时，绝对不能在工具执行或初始化逻辑中使用 console.log() 或 process.stdout.write()。

• 调试日志：所有打印日志、调试信息请全部使用 console.error() 输出，客户端会自动捕获并展示在控制台或日志文件中。