File System MCP Server

A minimal Model Context Protocol (MCP) server that provides secure file read and write operations within a sandbox directory. This server is designed to work with MCP clients and includes a Gradio web interface for interactive use.

Features

This MCP server provides two simple tools:

• read_file - Read the contents of a file from the sandbox directory
• write_file - Write content to a file in the sandbox directory (creates file if it doesn't exist)

Security Features

• Sandbox Directory: All file operations are restricted to the sandbox/ directory
• Path Resolution: Paths are automatically resolved relative to the sandbox, preventing access to files outside the sandbox
• Automatic Directory Creation: Parent directories are automatically created when writing files

Installation

1. Install Python 3.8 or higher

2. Install the required dependencies:

pip install -r requirements.txt

The main dependencies are:

• openai-agents - OpenAI Agents SDK (includes MCP support)
• openai - OpenAI SDK (used for Gemini API compatibility)
• gradio - Web interface framework
• python-dotenv - Environment variable management

3. Install the MCP Python SDK:

pip install git+https://github.com/modelcontextprotocol/python-sdk.git

Or if available on PyPI:

pip install mcp

Configuration

Environment Variables

Create a .env file in the project root:

GOOGLE_API_KEY=your_google_api_key_here

Get your API key from Google AI Studio.

MCP Client Configuration

To use this MCP server with an MCP client (like Cursor), add it to your MCP configuration file.

For Cursor, add to your MCP settings (typically in ~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "file-system": {
      "command": "python3",
      "args": ["/absolute/path/to/file-system-mcp-server/server.py"],
      "env": {}
    }
  }
}

Or if you've installed it in a virtual environment:

{
  "mcpServers": {
    "file-system": {
      "command": "/path/to/venv/bin/python",
      "args": ["/absolute/path/to/file-system-mcp-server/server.py"],
      "env": {}
    }
  }
}

See example_config.json for a reference configuration.

Usage

Running the MCP Server

The server uses stdio (standard input/output) for communication:

python server.py

Using the Gradio Web Interface

The project includes a Gradio web interface (app.py) that provides an interactive way to use the MCP server with Google's Gemini model:

python app.py

This will:

1. Launch a web interface (typically at http://127.0.0.1:7860)
2. Connect to the MCP server
3. Use Gemini 2.0 Flash model to process natural language prompts
4. Execute file operations within the sandbox directory

The interface allows you to enter prompts like:

• "Write a story about a robot"
• "Read the file test.md"
• "Create a file called notes.txt with some content"

Example Tool Usage

Once connected via an MCP client, you can use the tools:

Read a file:

{
  "name": "read_file",
  "arguments": {
    "path": "test.md"
  }
}

Write a file:

{
  "name": "write_file",
  "arguments": {
    "path": "hello.txt",
    "content": "Hello, World!"
  }
}

Note: All paths are relative to the sandbox/ directory. The server automatically creates the sandbox directory if it doesn't exist.

Project Structure

file-system-mcp-server/
├── server.py              # MCP server implementation
├── app.py                 # Gradio web interface
├── requirements.txt       # Python dependencies
├── example_config.json    # Example MCP client configuration
├── README.md             # This file
└── sandbox/              # Sandbox directory for file operations
    ├── hello.txt
    ├── sample.txt
    └── test.md

How It Works

MCP Server (server.py)

1. Initializes an MCP server named "basic-fileserver"
2. Creates a sandbox/ directory for secure file operations
3. Provides two tools:
   • read_file: Reads files from the sandbox directory
   • write_file: Writes files to the sandbox directory
4. All paths are resolved relative to the sandbox directory for security

Gradio Interface (app.py)

1. Loads environment variables (including GOOGLE_API_KEY)
2. Creates a Gemini client using OpenAI-compatible API
3. Connects to the MCP server via stdio
4. Uses OpenAI Agents SDK to create an agent with MCP server access
5. Processes natural language prompts and executes file operations

Security Notes

⚠️ Important Security Considerations:

• All file operations are restricted to the sandbox/ directory
• Absolute paths are sanitized to prevent directory traversal
• The sandbox directory is automatically created if it doesn't exist
• Files in the sandbox directory are excluded from git (see .gitignore)

Development

Testing

You can test the server directly:

# Test reading a file
python -c "
import asyncio
from server import read_file_tool
result = asyncio.run(read_file_tool({'path': 'hello.txt'}))
print(result.content[0].text)
"

Adding New Tools

To add new file operations, modify server.py:

1. Create a new async function (e.g., async def delete_file_tool(...))
2. Add the tool to the list_tools() function
3. Add a handler in the call_tool() function

Remember to keep all operations within the sandbox directory for security.

License

This project is provided as-is for use with the Model Context Protocol.