File Share MCP

An MCP server for bidirectional file sharing between AI agents and users, with a built-in web GUI.

The agent can list, read, and notify about files. The user can upload, download, and delete files via the GUI — all through a shared local folder.

Features

• MCP Tools for the AI agent:
  • get_shared_folder — Get the current shared folder path
  • list_shared_files — List all files available in the shared folder
  • share_file — Notify the user that a file is ready to download
  • preview_file — Read the content of a .txt or .md file (max 1 MB)
• Web GUI — Upload, download, preview, and delete files from a browser
• Zero config — works out of the box with sensible defaults (~/.file-share-mcp)
• Proxy-ready — optional integration with the file-share-mcp proxy

Quick Start with Cursor

Add this to your Cursor MCP configuration (~/.cursor/mcp.json or your workspace .cursor/mcp.json):

{
  "mcpServers": {
    "file-share": {
      "command": "npx",
      "args": ["-y", "file-share-mcp"]
    }
  }
}

Once added, restart Cursor. The GUI will be available at http://localhost:3005.

Quick Start with Claude Desktop

Add this to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "file-share": {
      "command": "npx",
      "args": ["-y", "file-share-mcp"]
    }
  }
}

Configuration (optional)

All configuration is done via environment variables, passed in the MCP env block or in a .env file inside the package directory.

| Variable | Default | Description | |---|---|---| | GUI_PORT | 3005 | Port for the web GUI | | MCP_DATA_DIR | ~/.file-share-mcp | Directory for configs.json and persistent data | | PROXY_URL | (none) | URL of the proxy server (optional) | | PROXY_APP_PATH | /file-share | Path to register on the proxy | | PROXY_APP_NAME | File Share MCP | Display name shown in the proxy dashboard |

Example: custom port and data directory

{
  "mcpServers": {
    "file-share": {
      "command": "npx",
      "args": ["-y", "file-share-mcp"],
      "env": {
        "GUI_PORT": "3010",
        "MCP_DATA_DIR": "C:/Users/YourName/my-shared-files"
      }
    }
  }
}

Example: with proxy integration

{
  "mcpServers": {
    "file-share": {
      "command": "npx",
      "args": ["-y", "file-share-mcp"],
      "env": {
        "PROXY_URL": "http://localhost:3000",
        "PROXY_APP_PATH": "/file-share",
        "PROXY_APP_NAME": "File Share MCP"
      }
    }
  }
}

Data & Logs

By default, all user data is stored in ~/.file-share-mcp/:

~/.file-share-mcp/
├── configs.json       # Saved configuration (shared folder path, etc.)
├── shared/            # Default shared folder
└── logs/
    └── server.log     # Application logs

This directory survives package updates and reinstalls.

Development

# Install dependencies
npm install
cd gui && npm install && cd ..

# Build (backend + frontend)
npm run build

# Start
npm start

Project structure

src/
├── mcp-server.ts       # MCP server (MASTER process)
├── gui.ts              # Express GUI server (WORKER process)
└── utils/
    ├── config-manager.ts
    ├── file-manager.ts
    ├── logger.ts
    └── generate-version.ts
gui/                    # React + Vite frontend (builds to ../public/)
public/                 # Built frontend (served by the GUI server)

License

ISC