FS-MCP: Universal File Reader & Intelligent Search MCP Server

English

🚀 Features

• 🧠 Intelligent Text Detection: Automatically identifies text files without relying on file extensions
• 📄 Multi-Format Support: Handles text files and document formats (Word, Excel, PDF, etc.)
• 🔒 Security First: Restricted access to configured safe directories only
• 📏 Range Reading: Supports reading specific line ranges for large files
• 🔄 Document Conversion: Automatic conversion of documents to Markdown with caching
• 🔍 Vector Search: Semantic search powered by AI embeddings
• ⚡ High Performance: Batch processing and intelligent caching support
• 🌐 Multi-language: Supports both English and Chinese content

📋 Table of Contents

• Quick Start
• Installation
• Configuration
• MCP Tools
• Vector Search
• Supported Formats
• Security Features
• Integration
• Development
• Contributing
• License

🚀 Quick Start

1. Clone and Install

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

Using uv (Recommended):

uv sync

Using pip:

pip install -r requirements.txt  # If you have a requirements.txt
# OR install directly
pip install fastmcp>=2.0.0 langchain>=0.3.0 python-dotenv>=1.1.0

2. Environment Configuration

Create a .env file in the project root:

# Security Settings
SAFE_DIRECTORY=.                    # Directory restriction (required)
MAX_FILE_SIZE_MB=100                # File size limit in MB

# Encoding Settings
DEFAULT_ENCODING=utf-8

# AI Embeddings Configuration (for vector search)
OPENAI_EMBEDDINGS_API_KEY=your-api-key
OPENAI_EMBEDDINGS_BASE_URL=http://your-embedding-service/v1
EMBEDDING_MODEL_NAME=BAAI/bge-m3    # Or your preferred model
EMBEDDING_CHUNK_SIZE=1000

3. Start the Server

python main.py

The server will start on http://localhost:3002 and automatically build the vector index.

🛠️ Installation

System Requirements

• Python: 3.12 or higher
• OS: Windows, macOS, Linux
• Memory: 4GB+ recommended for vector search
• Storage: 1GB+ for caching and indexes

Dependencies

Core dependencies are managed in pyproject.toml:

• fastmcp>=2.0.0 - MCP server framework
• langchain>=0.3.0 - AI and vector search
• python-dotenv>=1.1.0 - Environment management
• Document processing libraries (pandas, openpyxl, python-docx, etc.)

⚙️ Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SAFE_DIRECTORY | . | Root directory for file access | | MAX_FILE_SIZE_MB | 100 | Maximum file size limit | | DEFAULT_ENCODING | utf-8 | Default file encoding | | OPENAI_EMBEDDINGS_API_KEY | - | API key for embedding service | | OPENAI_EMBEDDINGS_BASE_URL | - | Embedding service URL | | EMBEDDING_MODEL_NAME | BAAI/bge-m3 | AI model for embeddings | | EMBEDDING_CHUNK_SIZE | 1000 | Text chunk size for processing |

Advanced Configuration

For production deployments, consider:

• Setting up rate limiting
• Configuring log rotation
• Using external vector databases
• Setting up monitoring

🔧 MCP Tools

... View full README on GitHub