Skip to main content
Glama
deenesjakoruzh
jibixn

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.

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

Related MCP Servers