AI导哈

文件系统工具服务器

一个基于Python的模型上下文协议（MCP）服务器，安全地暴露了macOS、Linux和Windows上的基本文件系统工具（列表、搜索、复制、移动）。

  • by harshaga55
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 harshaga55/local-filesystem-mcp-server

使用说明

本地文件系统MCP服务器

基于Python的模型上下文协议（MCP）服务器，在macOS、Linux和Windows上安全地公开基本的文件系统工具（列表、搜索、复制、移动）。

特性

  • 具有递归控制、隐藏文件可见性和符号链接处理的目录列表。
  • 具有区分大小写切换和目录/文件匹配选项的全局式搜索。
  • 复制和移动支持文件、目录和符号链接的帮助程序（具有跨设备回退）。
  • 默认情况下，操作范围仅限于工作目录，以限制访问。
  • 用于文本提取和分析的可选Azure文档智能工具。

先决条件

设置

poetry install

通过stdio运行MCP服务器（与Claude Desktop、VS Code、Cursor等兼容）：

poetry run start --transport stdio

配置

服务器启动时使用本地定义的任何环境变量 .env 文件（放在README旁边）。shell中已存在的变量优先。

服务器基础知识

关键环境变量（均为可选）存在 .env:

  • MCP_SERVER_PORT --HTTP传输的侦听端口（默认为 8000).
  • MCP_TRANSPORT --选择 stdio, sse，或 streamable-http 当通过CLI启动时。
  • MCP_SERVER_LOG_LEVEL --调整FastMCP日志记录(INFO 默认情况下）。
  • MCP_FS_ROOTS --工具可以访问的其他根目录的可选列表。

当 MCP_FS_ROOTS 设置后，提供一个或多个由操作系统路径分隔符分隔的绝对路径(: 在macOS/Linux上， ; 在Windows上）。如果省略，服务器将限制对启动它的工作目录的访问。

运输选择

支持所有FastMCP传输：

  • stdio （默认）保持与桌面IDE客户端的兼容性。
  • sse （服务器发送事件）公开了适用于HTTP客户端的流端点。
  • streamable-http 公开了MCP 1.19中引入的流式HTTP传输。

集 MCP_TRANSPORT 在你的 .env （或通行证 --transport 在命令行上）选择要启动的传输实例。当选择HTTP传输时(sse 或 streamable-http)，服务器侦听 http://127.0.0.1:<port>/，使用 MCP_SERVER_PORT 如果提供。

MCP_TRANSPORT=sse
MCP_SERVER_PORT=9000

运行命令示例：

# Read transport choice from .env
poetry run start

# Override transport at runtime
poetry run start --transport streamable-http

Azure文档智能（可选）

文档分析工具仅在以下Azure凭据存在时注册（在 .env 或外壳）：

  • AZURE_DOCUMENT_ENDPOINT
  • AZURE_DOCUMENT_KEY
  • AZURE_DOCUMENT_MODEL_ID （默认为 prebuilt-layout 如果省略）

如果缺少这些变量，服务器将继续运行，但跳过Azure支持的工具，因此不会暴露任何敏感信息。

快速Azure设置：

  1. 如果您还没有钥匙，请登录(az login 或Azure门户）使用拥有您的文档智能资源的订阅。
  2. 创建或定位 文档智能 （又名。 表单识别器)所需区域的资源。
  3. 从中获取端点URL和其中一个访问密钥 密钥和端点 刀片(az cognitiveservices account keys list --name <name> --resource-group <rg> 也工作）。
  4. 填充 .env 使用endpoint/key（和可选的模型id），然后重新启动服务器。

如果您已经拥有团队中其他人的有效端点和密钥，请跳过登录步骤——只需将这些值直接放入 .env 工具将被激活。

启用这些工具时安装客户端库（任一软件包都可以使用）：

poetry add azure-ai-documentintelligence
# or, for the older SDK
poetry add azure-ai-formrecognizer

可用工具

工具 目的 关键参数
files_list_directory 列出目录条目（可选递归）。 path?, recursive=false, include_hidden=false, follow_symlinks=false, max_depth=5, limit=200
files_find 全局搜索路径下的文件/目录。 pattern, path?, include_hidden=false, case_sensitive=true, match_files=true, match_directories=true, max_depth=25, limit=500
files_copy 复制文件/目录/符号链接。 source, destination, overwrite=false, recursive=true
files_move 移动（剪切）文件/目录/符号链接。 source, destination, overwrite=false, recursive=true
analysis_word_count* 通过Azure文档智能获取单词/字符计数。 path, model_id?
analysis_extract_text* 检索最多8k个字符的提取文本。 path, model_id?, max_characters=8000

*仅在Azure凭据可用时注册。

资源：

  • file://{path} --公开文件元数据（并在可能的情况下提供UTF-8预览）。

每个工具都返回结构化的JSON和文本摘要，使响应对用户界面和自动化代理都很友好。

与MCP客户端集成

大多数MCP客户端接受stdio命令。配置您的客户端以运行 poetry run start （或等效的venv路径）并使用stdio传输选项进行连接。支持流式HTTP/SSE的客户端可以在您启动时以打印的本地URL为目标 poetry run start --transport sse （或 streamable-http).

了解有关MCP的更多信息，请访问 模型上下文协议.io.

相关 MCP