Skip to main content
Glama
deenesjakoruzh
jibixn

MCP File System Agent

by jibixn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP 文件系统代理

一个基于 LangChain、Ollama、FastMCP 和 MCP 构建的本地 智能文件系统助手。

该项目演示了 LLM 如何自主选择并使用 MCP 服务器暴露的工具来执行文件相关操作，例如读取、列出、写入和搜索文件。

架构

                         User
                           │
                           ▼
                  ┌─────────────────┐
                  │  LangChain      │
                  │     Agent       │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   Ollama LLM    │
                  │   Qwen3 1.7B    │
                  └────────┬────────┘
                           │
                    Tool selection
                           │
                           ▼
                ┌──────────────────────┐
                │ LangChain MCP Adapter│
                └──────────┬───────────┘
                           │
                       MCP / HTTP
                           │
                           ▼
                ┌──────────────────────┐
                │     FastMCP Server   │
                │   localhost:8000/mcp │
                └──────────┬───────────┘
                           │
             ┌─────────────┼─────────────┐
             ▼             ▼             ▼
        read_file     list_files    write_file
             │
             ▼
       Local File System

Related MCP server: OmniMCP-Container

功能特性

  • 基于 MCP 的工具架构

  • 使用 HTTP 传输的本地 FastMCP 服务器

  • 支持工具调用的 LangChain 代理

  • 通过 Ollama 进行本地 LLM 推理

  • PDF 文件读取

  • DOCX 文件读写

  • 带扩展名过滤的文件列表

  • 在 PDF 和 DOCX 文件内搜索

  • 使用 LangGraph 检查点机制实现对话状态管理

  • LLM 自动选择工具

技术栈

  • Python

  • LangChain

  • LangGraph

  • Ollama

  • Qwen3 1.7B

  • FastMCP

  • 模型上下文协议（MCP）

  • langchain-mcp-adapters

  • PyPDF

  • python-docx

项目结构

MCP/
│
├── tests/
│   └── sample.docx
│
├── fs_mcp.py
├── main.py
├── requirements.txt
└── README.md

安装

1. 克隆仓库

git clone https://github.com/jibixn/File-System-Tools-MCP
cd MCP

2. 安装 Python 依赖

pip install -r requirements.txt

3. 安装 Ollama

从官方网站安装 Ollama，并确保它在本地运行。

然后拉取模型：

ollama pull qwen3:1.7b

您可以通过以下命令验证模型是否可用：

ollama list

运行项目

该项目使用两个进程，因为 MCP 服务器通过 HTTP 与客户端通信。

终端 1 — 启动 MCP 服务器

在项目根目录下运行此命令：

python fs_mcp.py

服务器应可在以下地址访问：

http://127.0.0.1:8000/mcp

终端 2 — 启动代理

在项目根目录下打开另一个终端：

python main.py

然后您可以输入如下请求：

Read the file in tests folder named sample.docx and provide me the summary.

或：

List all PDF files in the tests folder.

或：

Write "Hello, World!" to tests/output.docx.

代理工作流程示例

对于如下请求：

Read the file in tests folder named sample.docx and provide me the summary.

代理将执行以下操作：

User request
     │
     ▼
LLM analyzes request
     │
     ▼
LLM selects read_file
     │
     ▼
LangChain MCP Adapter
     │
     ▼
MCP HTTP request
     │
     ▼
FastMCP read_file()
     │
     ▼
python-docx reads file
     │
     ▼
Tool result returned to agent
     │
     ▼
LLM summarizes content
     │
     ▼
Final response

环境要求

建议使用 Python 3.11 或更高版本。

必须安装 Ollama 并在本地运行。

必须提供 Qwen 模型：

ollama pull qwen3:1.7b

您也可以使用推理提供商提供的模型。

依赖项

项目的直接依赖项如下：

fastmcp==3.4.7
langchain==1.3.14
langchain-mcp-adapters==0.3.2
langchain-ollama==1.1.0
langgraph-checkpoint==4.2.0
pypdf==6.14.2
python-docx==1.2.0

未来改进

  • 支持更多文件格式

  • 添加文件删除和目录创建工具

  • 添加更强的路径验证和沙箱机制

  • 为远程 MCP 服务器添加身份验证

  • 添加流式响应

  • 添加更丰富的文档解析

  • 添加持久化对话存储

  • 为数据库、GitHub 或网络搜索添加额外的 MCP 服务器

  • 使用更大的本地模型提高工具选择的可靠性

学习目标

该项目演示了以下组件之间的交互：

LLM
 ↓
LangChain Agent
 ↓
Tool Calling
 ↓
MCP Client
 ↓
MCP Protocol
 ↓
FastMCP Server
 ↓
Python Functions

它旨在作为使用模型上下文协议（MCP）和本地托管的 LLM 构建智能应用程序的实践示例。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

  • uldl
    sh.uldl

    Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.

    File SystemsCloud StorageAgent Orchestration
    2
  • flockfsOAuth
    com.flockfs

    A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.

    File SystemsVersion ControlDeveloper Tools
    1
  • saagarpatel.dev PortfolioA
    io.github.saagpatel

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

    SearchDocumentation Access
    82
  • Fast.ioA
    io.fast.mcp

    Fastio gives your team and AI agents a workspace for each project, bringing source files, comments and new work together. Connect a compatible MCP client to find files, answer questions from project material, and save results where the team can review and use them. \ Sign in through Fastio and choose the workspaces the connection can reach. Read Only connections expose read tools; Read & Write connections also allow changes. \ • **Files and folders:** browse, read, upload, and organize files, with version history and trash. • **Search:** find files by keyword; search file content and meaning when Deep Indexing is enabled and files have been processed. • **Metadata:** read, set, and search metadata fields, including extracted fields where available. • **Shares:** create and manage shares for sending or collecting files. • **Comments and members:** read and add comments, and manage workspace membership within your permissions. • **Activity:** search workspace events to see what changed. \ Hosted by Fastio, with no server installation required. \ • **Claude and most MCP clients:** https://mcp.fast.io/mcp/tools • **ChatGPT:** https://mcp.fast.io/mcp/operations • **ChatGPT and Codex:** Fastio plugin • **Claude Code, Cursor and similar coding agents:** https://mcp.fast.io/mcp/code • **Setup and client-specific capabilities:** https://mcp.fast.io/docs \ Paid plans. Monthly plans include a trial of up to 30 days. A card is required, and billing begins when the trial ends or trial credits run out, whichever comes first. No free plan.

    Cloud StorageFile SystemsRAG Systems
    373

Related MCP Servers