Skip to main content
Glama

FileN-MCP Server

Unofficial Model Context Protocol (MCP) server for Filen (filen.io), built on the official @filen/sdk TypeScript SDK.

Unofficial disclaimer: This project is not affiliated with, endorsed by, or supported by Filen Cloud Dienste UG. It is a community effort and comes with no warranty. Use at your own risk. Filen itself has no official MCP server (yet) — if one is released, prefer the official one.

The server speaks MCP over stdio only (no network listener) and exposes your Filen cloud drive as tools to MCP clients such as Claude Desktop or Cursor.

Tools

All cloud paths are absolute, starting at / (the root of your Filen drive).

Tool

Description

Read-only

list_directory

List entries of a directory (path, optional recursive)

yes

stat

Metadata of a file/folder: type, uuid, size, mtimeMs, birthtimeMs (path)

yes

read_file

Read a file as UTF-8 text (path); refuses non-files and files > 5 MB (use download_file for those)

yes

search_files

Case-insensitive substring search over paths (query, optional path, default /)

yes

write_file

Write UTF-8 text to a cloud file, creating/overwriting it (path, content)

no

upload_file

Upload a local file/directory to the cloud (source local path, path cloud destination)

no

download_file

Download a cloud file/directory to a local path (path, destination)

yes

create_folder

Create a folder, including intermediate directories (path)

no

delete_item

Delete a file/folder (path, permanent=false → trash; permanent=true → permanent)

no

Tool errors are returned as MCP tool results with isError: true and a text message starting with Error:.

Related MCP server: drive-mcp

Requirements

  • Node.js >= 20

  • A Filen account and either an API key or your email/password (see below)

Setup

git clone https://github.com/Mantic0re1337/FileN-MCP.git
cd FileN-MCP
npm install
npm run build

Run it directly:

FILEN_API_KEY="your-api-key" npm start

Or inspect it with the MCP Inspector:

FILEN_API_KEY="your-api-key" npm run inspect

Credentials (environment variables only)

The server never hardcodes credentials. Provide them via environment variables:

Variable

Purpose

FILEN_API_KEY

Your Filen API key. Preferred option — no 2FA needed on subsequent calls.

FILEN_EMAIL + FILEN_PASSWORD

Account login instead of an API key.

FILEN_2FA_CODE

2FA code, required with email/password login if your account has two-factor authentication enabled.

Getting an API key

Per the official Filen API docs, the API key is returned by the POST /v3/login response (email + derived password + 2FA code), and each API call is then authenticated with Authorization: Bearer <api_key>. In practice the easiest way to obtain it is the Filen CLI: log in once (including 2FA) and run filen export-api-key (see docs.cli.filen.io and the rclone docs, which state this is currently only possible via the CLI). The SDK does the login under the hood when you call filen.init({ apiKey }).

Notes:

  • The API key itself needs no 2FA — fetch it once and set it as FILEN_API_KEY in your MCP client config; the server authorizes automatically on every start.

  • The API key becomes invalid if you change your Filen account password — then export a new one.

  • Treat the API key like a password: only in the MCP client config or a git-ignored .env, never in the repo.

If neither FILEN_API_KEY nor FILEN_EMAIL + FILEN_PASSWORD is set, the server prints a clear error and exits with code 1.

You can also put them in a local .env file (git-ignored) and load it with your favorite dotenv runner, e.g. npx dotenvx run -- npm start.

Client configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "filen": {
      "command": "node",
      "args": ["/absolute/path/to/FileN-MCP/dist/index.js"],
      "env": {
        "FILEN_API_KEY": "your-api-key"
      }
    }
  }
}

(Use FILEN_EMAIL, FILEN_PASSWORD and optionally FILEN_2FA_CODE instead of FILEN_API_KEY if you prefer.)

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "filen": {
      "command": "node",
      "args": ["/absolute/path/to/FileN-MCP/dist/index.js"],
      "env": {
        "FILEN_API_KEY": "your-api-key"
      }
    }
  }
}

Replace /absolute/path/to/FileN-MCP with the real clone path on your machine.

Security notes

  • stdio only: the server listens exclusively on stdio on the local machine; it opens no network port. It only talks to Filen's API endpoints.

  • Zero-knowledge stays intact: all encryption/decryption happens locally inside @filen/sdk using your own keys. The server never sees plaintext keys beyond what the SDK needs, and Filen's servers never see your file contents.

  • Credentials via env only: no credentials are hardcoded or committed; .env is git-ignored.

  • read_file has a 5 MB cap so a single tool call cannot pull huge files into the model context; use download_file for larger files.

  • delete_item defaults to the trash (permanent=false); permanent deletion requires explicitly setting permanent=true.

  • Unofficial & use at your own risk: this is a community server, not affiliated with Filen. API/SDK behavior may change without notice.

Development

npm run dev      # build + run
npm run build    # compile TypeScript to dist/
npm start        # run dist/index.js
npm run inspect  # MCP Inspector

License

AGPL-3.0 — matching the license of the Filen SDK (@filen/sdk).

Available Tools

9 tools
create_folderCreate folderB

Create a folder in the Filen cloud. Intermediate directories are created recursively if missing.

Inputs: path (required).

delete_itemDelete itemA
Destructive

Delete a file or directory from the Filen cloud. By default the item is moved to the trash; set permanent=true to delete it permanently.

Inputs: path (required), permanent.

download_fileDownload fileA
Read-only

Download a file (or directory) from the Filen cloud to a local destination path on the machine running this server.

Inputs: path (required), destination (required).

list_directoryList directoryB
Read-only

List the entries of a Filen cloud directory. Paths are absolute, starting at '/'.

Inputs: path (required), recursive.

read_fileRead fileA
Read-only

Read a text file from the Filen cloud and return its UTF-8 content. Refuses files that are not regular files or larger than 5 MB (use download_file for those).

Inputs: path (required).

search_filesSearch filesB
Read-only

Search the Filen cloud for files/directories whose path contains the query (case-insensitive substring match).

Inputs: query (required), path.

statStat itemA
Read-only

Get metadata (type, uuid, size, timestamps) of a file or directory in the Filen cloud.

Inputs: path (required).

upload_fileUpload fileA

Upload a local file (or directory) from the machine running this server into the Filen cloud. Parent directories are created automatically.

Inputs: path (required), source (required).

write_fileWrite fileB
Destructive

Write UTF-8 text content to a file in the Filen cloud, creating or overwriting it. Parent directories are created automatically.

Inputs: path (required), content (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct operation, but two pairs have adjacent purposes: write_file vs upload_file (both create content) and read_file vs download_file (both retrieve content). The descriptions disambiguate them well (read_file explicitly points to download_file for large/binary files), so confusion is minor.

    Naming Consistency4/5

    Nearly all tools follow a verb_noun pattern (list_directory, read_file, search_files, write_file, upload_file, download_file, create_folder, delete_item). The lone exception is 'stat', which breaks the pattern as a bare verb, but it is a recognizable filesystem convention.

    Tool Count5/5

    Nine tools is well-scoped for a cloud file storage server, covering listing, metadata, reading, writing, transferring, folder creation, and deletion without redundancy. Every tool earns its place.

    Completeness4/5

    Core CRUD and transfer operations are covered, but notable gaps remain: there is no move/rename or copy tool, and delete_item mentions a trash but there is no restore-from-trash or list-trash operation. Agents can work around these (e.g. download+upload to move) but not the trash dead end.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Manage Proton Drive from Claude, Codex, VS Code/Copilot, and any MCP client through Proton's official CLI. Authentication and encrypted Drive behavior stay with Proton's tooling.
      96 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables an MCP client to search, read, download, create, edit, organize, trash, untrash, and share files in a single Google Drive account over stdio using your own Google OAuth client.
      17
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients to browse and read files, folders, photo albums, and metadata in the user's cloud drive through a read-only stdio server, including folder listing, full-text search, glob-based finding, file reading, item stats, and storage quota reporting.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables searching, listing, reading metadata and contents, uploading, downloading, creating folders, and trashing Google Drive files through MCP tools backed by the Google Drive API. It authenticates with a Google OAuth access token and can run as a stdio MCP server via npx or Docker.
      78 npm
      MIT