Python MCP实战：从零搭建本地文件系统服务器，让Cursor/Claude自由读取本地项目文件（附完整安全代码）

本文仅用于本地开发学习MCP服务拥有本地文件读写权限存在敏感文件泄露、路径穿越风险请严格遵守以下安全规范仅授权AI访问非隐私、无密钥、无配置文件的项目目录禁止直接扫描系统根目录、用户桌面、数据库密钥文件夹代码内置目录白名单校验生产环境必须开启路径限制防止../路径穿越攻击stdio模式仅本地客户端使用streamable-http HTTP模式禁止公网暴露仅本地localhost访问本教程技术仅供个人开发调试请勿用于第三方远程文件读取、批量扫描他人设备。一、前言日常使用Cursor、Claude Desktop、VS Code MCP客户端时AI只能处理对话内粘贴的代码片段无法直接读取本地项目目录、批量检索源码、统计文件结构、预览日志文件。核心原因AI客户端默认无本地文件系统操作权限而MCPModel Context Protocol 模型上下文协议是Anthropic推出的标准化AI本地工具通信协议相当于AI的通用USB接口一次开发MCP服务所有支持MCP的AI客户端均可无缝调用本地文件能力。本文基于Python FastMCP SDK从零实现文件搜索、目录统计、文件预览三大工具完整兼容Cursor、Claude Desktop附带安全权限校验、客户端全平台配置教程。适用场景本地项目批量检索py/json配置文件代码目录结构统计、文件大小汇总日志、源码快速预览无需手动打开文件AI自动分析本地项目工程结构二、MCP协议通俗原理把MCP理解为AI客户端的标准化外设接口类比事物MCP对应概念电脑主机Claude/Cursor/VS Code AI客户端U盘/外设自定义Python本地工具服务USB通信标准MCPJSON-RPC/Streamable HTTP/stdio即插即用配置客户端mcpServers配置项传统方案不同AI工具需要单独开发插件、适配各自私有APIMCP标准化后一套MCP服务全平台AI客户端通用大幅降低本地工具开发成本。三、环境部署1. Python版本要求Python ≥ 3.10# 查看版本python3--version2. 安装依赖库# MCP官方SDK HTTP服务框架pipinstallmcp fastapi uvicorn依赖说明mcpFastMCP官方Python开发库快速注册AI可调用工具fastapiuvicorn提供Streamable HTTP服务传输通道3. 项目初始化# 创建项目文件夹mkdir-p~/my-file-mcpcd~/my-file-mcp四、完整MCP服务代码带安全白名单详细注释新建file_scanner.py增加目录白名单防护规避路径穿越漏洞 本地文件扫描MCP Server安全加固版 功能文件检索、目录统计、文件内容预览 安全限制仅允许访问预设白名单目录防止路径穿越攻击 importosfrompathlibimportPathfrommcp.server.fastmcpimportFastMCP# 安全配置允许访问的目录白名单自行修改 ALLOW_DIRS[Path(~/projects).expanduser(),Path(~/code).expanduser()]# 转换为绝对路径用于校验ALLOW_ABS[p.resolve()forpinALLOW_DIRS]# 初始化MCP服务mcpFastMCP(File Scanner,description本地文件系统安全扫描工具仅读取白名单内目录支持文件检索、目录统计、源码预览,port8765)defis_path_safe(target_path:str)-bool:路径安全校验仅允许访问白名单目录拦截../路径穿越targetPath(target_path).resolve()# 判断目标路径是否在任一允许目录下forsafe_dirinALLOW_ABS:ifstr(target).startswith(str(safe_dir)):returnTruereturnFalsemcp.tool()defsearch_files(directory:str,pattern:str*.py,max_depth:int3)-str: 递归搜索指定目录下匹配后缀的文件 Args: directory: 目标检索目录必须在白名单内 pattern: 文件匹配规则如 *.py、*.json max_depth: 最大递归深度避免遍历过多文件 Returns: 匹配到的文件路径列表 # 安全校验ifnotis_path_safe(directory):returnf权限拒绝{directory}不在允许访问目录列表中请修改ALLOW_DIRS配置basePath(directory)ifnotbase.exists():returnf错误目录不存在 ——{directory}results[]try:fordepthinrange(max_depth1):glob_rule**/*patternifdepth0elsepatternforfile_pathinbase.glob(glob_rule):iffile_path.is_file()andlen(results)50:results.append(str(file_path))exceptExceptionase:returnf文件搜索异常{str(e)}ifnotresults:returnf在{directory}未匹配到{pattern}文件最大深度{max_depth}returnf共找到{len(results)}个文件\n\n.join(results)mcp.tool()defdir_stats(path:str)-str: 统计目录文件总数、总大小、文件类型分布 Args: path: 目标统计目录 Returns: 结构化目录统计报告 ifnotis_path_safe(path):returnf权限拒绝{path}不在允许访问目录列表中pPath(path)ifnotp.exists():returnf错误路径不存在 ——{path}total_files0total_size0ext_count{}foriteminp.rglob(*):ifitem.is_file():total_files1sizeitem.stat().st_size total_sizesize suffixitem.suffixifitem.suffixelse(无后缀)ext_count[suffix]ext_count.get(suffix,0)1# 按文件数量降序排序sorted_extsorted(ext_count.items(),keylambdax:-x[1])lines[f 统计目录{path},f 文件总数量{total_files},f 目录总大小{total_size/1024:.1f}KB,,前10类文件分布]forext,numinsorted_ext[:10]:lines.append(f{ext}{num}个)return\n.join(lines)mcp.tool()defpreview_file(path:str,max_lines:int30)-str: 预览文件前N行内容避免一次性读取超大文件占满上下文 Args: path: 文件完整路径 max_lines: 最多预览行数默认30行 Returns: 文件元信息 头部内容预览 ifnotis_path_safe(path):returnf权限拒绝{path}不在允许访问目录列表中pPath(path)ifnotp.exists()ornotp.is_file():returnf错误文件不存在或非文件 ——{path}try:withopen(p,r,encodingutf-8,errorsreplace)asf:all_linesf.readlines()previewall_lines[:max_lines]exceptExceptionase:returnf文件读取失败{str(e)}file_sizep.stat().st_size total_line_numlen(all_lines)header(f 文件路径{path}\nf文件大小{file_size/1024:.1f}KB | 总行数{total_line_num}\nf预览前{min(max_lines,total_line_num)}行内容\n\n)returnheader.join(preview)if__name____main__:# Streamable HTTP 本地服务仅localhost访问mcp.run(transportstreamable-http)启动服务命令python file_scanner.py正常输出示例INFO: Uvicorn running on http://0.0.0.0:8765 INFO: Application startup complete.五、AI客户端接入配置区分Mac/Windows5.1 Claude Desktop 配置Mac配置文件路径~/Library/Application Support/Claude/claude_desktop_config.jsonWindows配置文件路径%APPDATA%\Claude\claude_desktop_config.json配置JSONstdio传输模式推荐本地使用{mcpServers:{file-scanner:{command:python,args:[~/my-file-mcp/file_scanner.py],transport:stdio}}}修改完成后重启Claude Desktop自动加载MCP服务。5.2 Cursor 编辑器配置打开Cursor → Settings → MCP → Add new MCP Server配置参数| 配置项 | 填写内容 || Name | file-scanner || Command | python || Arguments | ~/my-file-mcp/file_scanner.py || Transport | stdio |保存后刷新MCP列表显示服务在线即连接成功。六、实操调用示例客户端连接成功后直接对话发送指令即可自动调用文件工具检索项目所有Python文件调用file-scanner扫描~/projects目录找出所有*.py文件最大深度3统计目录文件结构统计~/projects目录总文件数量、总大小展示各类文件占比预览源码文件读取~/projects/utils.py前20行代码并展示文件信息七、进阶扩展工具模板基于mcp.tool()装饰器可快速扩展更多本地自动化能力推荐开发工具函数实现功能git_log读取Git仓库最近提交记录log_tail实时读取日志末尾内容dir_diff对比两个目录文件差异docker_list列出本地运行容器cron_check读取系统定时任务配置新增工具仅需定义函数、增加参数注解MCP会自动生成工具描述供AI识别。八、安全加固生产优化方案严格目录白名单代码内置ALLOW_DIRS拦截路径穿越禁止开放系统根目录限制文件读取行数preview_file限制最大预览行数防止超大文件填满LLM上下文HTTP模式禁止公网暴露streamable-http仅本地localhost访问不开放0.0.0.0给局域网增加文件大小校验可新增代码判断文件体积拒绝读取超过1MB大文件日志记录所有文件操作添加本地日志审计AI全部文件访问行为。九、常见踩坑FAQQ1客户端识别不到MCP服务A检查Python路径是否正确、配置文件路径区分Mac/Windows修改配置后重启客户端确认mcp库版本≥1.0。Q2调用文件工具提示权限拒绝A将目标目录添加到代码顶部ALLOW_DIRS白名单重启MCP服务生效。Q3启动服务报端口占用A修改FastMCP初始化时portxxxx更换端口同步修改客户端配置。Q4读取中文文件乱码A代码已使用encodingutf-8, errorsreplace特殊编码文件可自行调整编码参数。十、全文总结MCP协议统一AI本地工具标准一份服务兼容Cursor、Claude、VS Code多客户端本文实现安全版文件扫描MCP服务内置路径白名单规避文件读取安全漏洞通过mcp.tool()装饰器极简开发自定义本地工具轻松扩展Git、容器、日志自动化能力核心价值打破AI只能操作对话文本的限制让AI直接接管本地项目分析、批量文件处理工作。本教程基于Python MCP SDK v1.x编写代码可直接本地运行仅用于个人开发学习。