Skip to main content
Glama
Sign In
deenesjakoruzh
MCP File System Agent

MCP File System Agent

by jibixn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP File System Agent

M8ven Score

A local agentic file-system assistant built with LangChain, Ollama, FastMCP, and MCP.

The project demonstrates how an LLM can autonomously select and use tools exposed by an MCP server to perform file-related operations such as reading, listing, writing, and searching files.

Architecture

                         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

Features

  • MCP-based tool architecture

  • Local FastMCP server using HTTP transport

  • LangChain agent with tool calling

  • Local LLM inference through Ollama

  • PDF file reading

  • DOCX file reading and writing

  • File listing with extension filtering

  • Searching inside PDF and DOCX files

  • Conversation state using LangGraph checkpointing

  • Automatic tool selection by the LLM

Tech Stack

  • Python

  • LangChain

  • LangGraph

  • Ollama

  • Qwen3 1.7B

  • FastMCP

  • Model Context Protocol (MCP)

  • langchain-mcp-adapters

  • PyPDF

  • python-docx

Project Structure

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

Installation

1. Clone the repository

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

2. Install Python dependencies

pip install -r requirements.txt

3. Install Ollama

Install Ollama from the official website and make sure it is running locally.

Then pull the model:

ollama pull qwen3:1.7b

You can verify that the model is available with:

ollama list

Running the Project

The project uses two processes because the MCP server communicates with the client over HTTP.

Terminal 1 — Start the MCP server

Run this command from the project root:

python fs_mcp.py

The server should be available at:

http://127.0.0.1:8000/mcp

Terminal 2 — Start the agent

Open another terminal in the project root:

python main.py

You can then enter requests such as:

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

or:

List all PDF files in the tests folder.

or:

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

Example Agent Flow

For a request such as:

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

the agent performs the following:

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

Requirements

Python 3.11+ is recommended.

Ollama must be installed and running locally.

The Qwen model must be available:

ollama pull qwen3:1.7b

You can also use a model through an inference provider.

Dependencies

The project's direct dependencies are:

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

Future Improvements

  • Add support for more file formats

  • Add file deletion and directory creation tools

  • Add stronger path validation and sandboxing

  • Add authentication for remote MCP servers

  • Add streaming responses

  • Add richer document parsing

  • Add persistent conversation storage

  • Add additional MCP servers for databases, GitHub, or web search

  • Improve tool-selection reliability with larger local models

Learning Goals

This project demonstrates the interaction between:

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

It is intended as a practical example of building an agentic application with Model Context Protocol (MCP) and locally hosted LLMs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    ActivityStale
    ResponsivenessNo recent community 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
      https://uldl.sh/api/mcp
    • flockfs
      com.flockfs

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

      File SystemsVersion ControlDeveloper Tools
      1
      https://app.flockfs.com/mcp
    • saagarpatel.dev PortfolioA
      io.github.saagpatel

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

      SearchDocumentation Access
      122
      https://mcp.saagarpatel.dev/mcp
    • 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
      https://mcp.fast.io/mcp

    Related MCP Servers