python-mcp

Files.com MCP Server

The files-com-mcp Python package lets your AI application interact with Files.com. It is for local use only and supports STDIO only: your MCP client starts the package as a subprocess on the same machine.

For MCP connections over a network, use the Files.com hosted MCP service.

Set FILES_COM_API_KEY in the environment your client passes to the subprocess. The local package makes outbound requests to the Files.com API to perform site operations.

Files.com is the cloud-native, next-gen MFT, SFTP, and secure file-sharing platform that replaces brittle legacy servers with one always-on, secure fabric. Automate mission-critical file flows—across any cloud, protocol, or partner—while supporting human collaboration and eliminating manual work.

With universal SFTP, AS2, HTTPS, and 50+ native connectors backed by military-grade encryption, Files.com unifies governance, visibility, and compliance in a single pane of glass.

Introduction

The Files.com Python MCP package lets Claude Desktop and other local MCP clients upload and download files, query folders, manage users, and run automations on your Files.com site. It uses the permissions of your API key, and its actions are logged like those of any other API client.

The Python package supports local use over STDIO (standard input and output) only. Your MCP client starts it on the same machine and communicates directly with that process, without a network listener. The package still needs outbound access to the Files.com API.

What MCP Is

The Model Context Protocol (MCP) is a standard interface through which a Large Language Model calls real APIs as part of its work. An MCP server hands the model a set of tools, and each Files.com tool is an authenticated operation in your site. With the server connected, the model can:

• Transfer files between cloud and on-premises systems
• Query folders and file metadata
• Create and manage users
• Automate workflows such as archiving or sharing

Common Use Cases

Assistants for operations teams. An internal chatbot fetches or archives files on request.

Automated workflows. An agent reacts to an incoming support request, then retrieves or uploads the files the case needs.

Developer copilots. A development-focused LLM creates users, provisions folders, or reads files while debugging.

Local vs. Hosted MCP

Use the local Python package with clients that launch STDIO servers, including Claude Desktop.

For clients that connect to MCP over a network, use the Files.com hosted MCP service. Files.com operates the server, so you do not need to install the Python package. Running the Python package as an HTTP or SSE service is unsupported, including during development.

Install uv, register uvx files-com-mcp as an MCP server in your LLM client, and give it a Files.com API key in the FILES_COM_API_KEY environment variable.

https://pypi.org/project/files-com-mcp/

Installation

The files-com-mcp Python package lets your MCP client call the Files.com API through a process running on your machine. It supports local use over STDIO (standard input and output) only. For clients that connect to MCP over a network, use the Files.com hosted MCP service.

Requirements

Your MCP client must be able to start a local STDIO server. Your machine needs outbound access to the Files.com API.

The examples run the server with uvx, which is part of uv. It runs a Python tool in an isolated environment of its own, so there is nothing to install or configure by hand beyond uv itself. Install uv first. You can also run the server in Docker.

Registering The Server

Set your client's local STDIO server command to uvx with files-com-mcp as the argument. uvx downloads the package on first use and starts it each time your client launches the server.

The Claude Desktop configuration shows these settings in JSON. For other clients, follow their instructions for adding a local STDIO server.

Authentication

The server authenticates to Files.com with an API key, read from the FILES_COM_API_KEY environment variable that your client passes to it. The model can do exactly what the key's user can do, so create a key for this purpose with the permissions the agent needs and no more.

Restricting Local File Transfers

Optionally set FILES_COM_LOCAL_ROOT in your client's server environment to an existing absolute directory path, such as /home/user/Documents. Uploads can only read files within that directory and its children, and downloads can only write there. When the variable is omitted or empty, transfers can use any local path accessible to the server.

The server resolves .. and symbolic links before checking each path. Relative transfer paths are resolved from the server's working directory and must still stay inside the configured directory. A download can create a new file in an existing directory within the boundary. A nonempty value must name an existing absolute directory; otherwise, the server will not start.

This setting applies to local transfer paths. Files.com paths continue to follow the API key's permissions.

uvx files-com-mcp

FILES_COM_API_KEY=your-api-key uvx files-com-mcp

FILES_COM_API_KEY=your-api-key FILES_COM_LOCAL_ROOT=/home/user/Documents uvx files-com-mcp

Using With Claude

Claude Desktop uses the Files.com Python MCP package to call the Files.com API from your machine. This setup supports local use over STDIO (standard input and output) only. For a network connection to MCP, use the Files.com hosted MCP service.

Claude Desktop reads its MCP servers from claude_desktop_config.json. Add the entry on the right under mcpServers, replace the FILES_COM_API_KEY value with a Files.com API key, and restart Claude Desktop. The MCP quickstart shows where the file lives on each operating system, walking through the same steps for another server.

The entry starts the server with uvx, so uv has to be installed first; see Installation.

Once Claude has restarted, the Files.com tools appear in its tool list. Tools lists them by category and explains why it pays to enable only the ones a task needs.

To restrict local uploads and downloads, optionally add "FILES_COM_LOCAL_ROOT": "/home/user/Documents" alongside FILES_COM_API_KEY in the env object, using an existing absolute directory on your machine. Restart Claude Desktop after changing it. See Restricting Local File Transfers for details.

{
  "mcpServers": {
    "Files.com": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "files-com-mcp"
      ],
      "env": {
        "FILES_COM_API_KEY": "your-api-key"
      }
    }
  }
}

Running In Docker

The files-mcp repository includes a Dockerfile that packages the MCP server with Python 3.11 and every dependency it needs, so the machine running your MCP client needs Docker but not Python or uv.

The container is still a local STDIO server. Your MCP client starts it with docker run and sends and receives protocol messages over standard input and output. The container stops when the client closes standard input. It does not listen on a port or start an HTTP server. For clients that connect to MCP over a network, use the Files.com hosted MCP service.

Building The Image

Build the image once, and again when you want a newer release. By default, Docker builds the image for the builder's native architecture. Add #v and a release number to the repository address to build a specific release.

The image contains the package from the repository you build and the latest release of the files-com Python SDK that it depends on. To install a specific SDK release instead, add --build-arg FILES_COM_SDK_VERSION= and the version number.

Registering The Server

Set your client's local STDIO server command to docker with the arguments in the example, and put your API key in the server's environment as FILES_COM_API_KEY. Replace 501:20 with your own user and group IDs from id -u and id -g, and replace /Users/you with your home folder.

• -i keeps the container's standard input open for the protocol. Do not add -t. A terminal combines the output streams and breaks the protocol.
• --rm removes the container when the session ends. --init runs a small init process as the container's first process, which forwards stop signals to the server and reaps child processes.
• --user runs the server with your user and group IDs, so it can write to the downloads folder you create and the files it downloads belong to you.
• -e FILES_COM_API_KEY, without a value, copies the key from the environment your client passes, so the key does not appear in the command line.

The server writes its logs to standard error.

Uploads And Downloads

Mount host folders to make their files available inside the container. The image sets FILES_COM_LOCAL_ROOT=/work to restrict local uploads and downloads to /work. Create both host folders before starting the server, and make the downloads folder writable by the container's user. Mount the folder containing upload files at /work/uploads with read-only access and the downloads folder at /work/downloads with write access. Use their absolute host paths in the client configuration.

Docker may create missing host folders with permissions that prevent downloads. Create the folders with mkdir -p first, as shown in the example, and make sure the container's user can write to the downloads folder.

Transfer tools take paths inside the container, not paths on your machine. When you ask the model to transfer a file, give a container path under /work/uploads or /work/downloads, such as /work/downloads/report.pdf. The absolute host paths belong only in the -v mount arguments.

docker build -t files-com-mcp https://github.com/Files-com/files-mcp.git

mkdir -p "$HOME/Files.com/uploads" "$HOME/Files.com/downloads"

{
  "mcpServers": {
    "Files.com": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--user", "501:20",
        "-e", "FILES_COM_API_KEY",
        "-v", "/Users/you/Files.com/uploads:/work/uploads:ro",
        "-v", "/Users/you/Files.com/downloads:/work/downloads",
        "files-com-mcp"
      ],
      "env": {
        "FILES_COM_API_KEY": "your-api-key"
      }
    }
  }
}

FILES_COM_API_KEY=your-api-key docker run -i --rm --init \
  --user "$(id -u):$(id -g)" \
  -e FILES_COM_API_KEY \
  -v "$HOME/Files.com/uploads:/work/uploads:ro" \
  -v "$HOME/Files.com/downloads:/work/downloads" \
  files-com-mcp

Tools

The Files.com MCP server exposes the tools below, grouped by category: files, folders, sharing, users, logs, automations and the other Files.com resources. Each tool is one operation in your site, run with the permissions of the API key the server holds.

Keep The Toolset Focused

A model picks the right tool more reliably from a short list. If the LLM uses Files.com tools inconsistently, it is most likely choosing among too many. Most clients let you enable and disable an MCP server's tools one by one; enable only the ones the agent's task needs.

Automations

File System

Integrations

Logging

Sharing / Share Links

User Accounts

Authentication

The Files.com MCP uses API key authentication.

Authenticate with an API Key

Authenticating with an API key is the recommended authentication method for most scenarios, and is the method used in the examples on this site.

To use an API Key, first generate an API key from the web interface or via the API or an SDK.

Note that when using a user-specific API key, if the user is an administrator, you will have full access to the entire API. If the user is not an administrator, you will only be able to access files that user can access, and no access will be granted to site administration functions in the API.

Don't forget to replace the placeholder, YOUR_API_KEY, with your actual API key.

Sort and Filter

Several of the Files.com API resources have list operations that return multiple instances of the resource. The List operations can be sorted and filtered.

Sorting

To sort the returned data, pass in the sort_by method argument.

Each resource supports a unique set of valid sort fields and can only be sorted by one field at a time.

Special note about the List Folder Endpoint

For historical reasons, and to maintain compatibility with a variety of other cloud-based MFT and EFSS services, Folders will always be listed before Files when listing a Folder. This applies regardless of the sorting parameters you provide. These will be used, after the initial sort application of Folders before Files.

Filtering

Filters apply selection criteria to the underlying query that returns the results. They can be applied individually or combined with other filters, and the resulting data can be sorted by a single field.

Each resource supports a unique set of valid filter fields, filter combinations, and combinations of filters and sort fields.

Filter Types

Paths

Files.com preserves the spelling of file and folder paths while comparing them using shared case and Unicode rules. Use the SDK comparison helpers when matching paths locally.

Capitalization

Files.com uses case-insensitive path matching based on its fixed Unicode comparison map.

For example, the following paths have the same comparison key:

This behavior applies across:

• API requests
• Folder and file lookup operations
• Automations and workflows

See also: Case Sensitivity Documentation

Slashes

Use