mcp_file_explorer

acapuccio-2303/mcp_file_explorer

3.1

If you are the rightful owner of mcp_file_explorer and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP File Explorer is a secure server that allows AI agents to perform safe file operations within a sandboxed environment.

MCP File Explorer

A Model Context Protocol (MCP) server that exposes safe file operations (list, read, write) to an AI agent. It provides sandboxing, authentication, audit logging, and rate limiting to ensure secure and controlled access.

Features

  • Sandboxed file system – The AI can only read/write inside a dedicated folder.
  • JWT authentication – Tokens signed with scopes (read, write, admin) and expiration.
  • Audit logging – All operations are logged to SQLite.
  • Rate limiting – Prevents abuse by limiting requests per token.

Project Structure

mcp_file_explorer/
├── app/
│   ├── main.py        # FastAPI MCP server with endpoints
│   ├── auth.py        # JWT token creation & validation
│   ├── sandbox.py     # Secure sandbox file management (list/read/write)
│   ├── audit.py       # SQLite audit logging
│   ├── config.py      # Configuration loader (.env support)
│   └── schemas.py     # Pydantic schemas for requests/responses
├── create_token.py    # CLI tool to generate JWT tokens
├── test_server.py     # Script to generate tokens & show curl examples
├── audit/             # Folder containing SQLite audit database/logs
├── mcp_sandbox/       # Mounted sandbox directory for AI file access
├── requirements.txt   # Python dependencies
├── .env.example       # Example environment configuration
└── README.md          # Documentation

Quickstart

Clone the repo and set up the environment:

git clone https://github.com/acapuccio-2303/mcp-file-explorer.git
cd mcp-file-explorer
cp .env.example .env

Install dependencies:

pip install -r requirements.txt

Run the server locally:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Server runs on http://localhost:8000.

Testing

Start the server first:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Then run the test script:

python test_server.py

Example output:

---- TOKEN READ ----
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
---- TOKEN WRITE ----
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

=== LIST ===
curl -H 'Authorization: Bearer <TOKEN_READ>' http://127.0.0.1:8000/mcp/list_files

=== WRITE ===
curl -H 'Authorization: Bearer <TOKEN_WRITE>' -X POST -H 'Content-Type: application/json' \
     -d '{"path":"test.txt","content":"SGVsbG8gV29ybGQh","overwrite":true}' \
     http://127.0.0.1:8000/mcp/write_file

=== READ ===
curl -H 'Authorization: Bearer <TOKEN_READ>' \
     http://127.0.0.1:8000/mcp/read_file?path=test.txt

Now you can:

  • List files inside the sandbox.
  • Write a file (test.txt containing "Hello World!" in base64).
  • Read the file you just wrote.

Volumes

  • ./mcp_sandbox → Mounted sandbox for files accessible by AI.
  • ./audit → Folder containing SQLite audit log.

Security Notes

  • Keep MCP_SECRET_KEY strong and private.
  • Mount only the sandbox directory you want the AI to see.
  • Rotate JWT tokens frequently in production.