Skip to main content
Glama
adrianofoschi

opencloud-mcp

by adrianofoschi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

opencloud-mcp

A small Model Context Protocol server that lets an AI assistant search and read the files of an OpenCloud user. It is read-only: it can find and read files, nothing else. It was written for Ambrogio, and works with any MCP client that speaks Streamable HTTP.

Tool

What it does

search_files

Finds files by the words in their name and in their text. The text search uses OpenCloud's full-text index, so it also finds words inside PDFs and office documents when OpenCloud extracts their text with Apache Tika. Content matches come first, with an excerpt around the words. Each result has a link that opens the file in the OpenCloud web interface, for anyone who has access to it.

read_file

Returns the text of a file found by search_files. Text files are read as they are; PDFs and office documents go through Apache Tika. Long texts come in parts: the result gives nextOffset to read the next one.

The server sees exactly what the OpenCloud user sees. Create a dedicated user, give it the Viewer role in a space with the documents the assistant may read, and nothing else: OpenCloud enforces the permissions, not this server. Remember that whatever the assistant reads goes to the provider of its language model.

Requirements

  • OpenCloud with full-text search, FRONTEND_FULL_TEXT_SEARCH_ENABLED=true and an Apache Tika extractor, for content search.

  • An app token of the dedicated user: opencloud auth-app create --user-name=<user> --expiration=<duration>. App tokens expire: choose the duration and renew it before it ends.

Related MCP server: Company Data MCP Server

Configuration

Variable

Required

Meaning

OPENCLOUD_URL

yes

Base URL of OpenCloud, for example http://opencloud:9200 inside Docker.

OPENCLOUD_HOST

no

Host header to send when OPENCLOUD_URL is not the public host of OpenCloud; requests then also carry X-Forwarded-Proto: https.

OPENCLOUD_USER

yes

The dedicated user.

OPENCLOUD_APP_TOKEN

yes

Its app token.

TIKA_URL

no

Apache Tika, for example http://opencloud-tika:9998. Without it only text files can be read.

MCP_TOKEN

yes

Long random secret; MCP clients send it as Authorization: Bearer <token>.

HTTP_HOST, HTTP_PORT

no

Listen address, 0.0.0.0:3000 by default.

READ_MAX_CHARS

no

Characters returned by one read_file call, 8000 by default.

DOWNLOAD_MAX_BYTES

no

Largest file that is read, 20 MiB by default.

The MCP endpoint is POST /mcp, stateless. Requests with an Origin header are refused, so that no web page can use the server through a visitor's browser. GET /health answers ok for container health checks.

Run

services:
  opencloud-mcp:
    image: ghcr.io/adrianofoschi/opencloud-mcp:v0.1.0
    restart: unless-stopped
    env_file: opencloud-mcp.env

Put the server on a Docker network that both OpenCloud and the MCP client reach, and do not publish its port outside the home network. An Ambrogio agent connects to it with:

"mcp": {
  "url": "http://opencloud-mcp:3000/mcp",
  "auth": { "type": "bearer", "tokenEnv": "OPENCLOUD_MCP_TOKEN" },
  "tools": ["search_files", "read_file"]
}

Development

corepack enable
pnpm install
pnpm verify

pnpm verify runs the checks of CI: frozen install, audit, type check, tests and build. The tests use local fakes of OpenCloud and Tika that answer as OpenCloud 7.2 does. Enable the secret scan before committing: git config core.hooksPath .githooks with gitleaks on PATH.

Releases are tags vMAJOR.MINOR.PATCH equal to the version in package.json; CI then publishes the image to GHCR.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Sprinklr MCP Server

    daiict218
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants read-only access to Sprinklr data via MCP, allowing querying reports, searching cases, and calling Sprinklr API endpoints.
    4 npm
    ISC

  • Company Data MCP Server

    Sidrahhh
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only access to company data across PostgreSQL, MongoDB Atlas, and flat files through MCP tools, allowing AI assistants to query and retrieve information via natural language.
    -

  • MailBridge MCP

    gexiro-global
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.
    Apache 2.0

  • VFS DMS ChatGPT Plugin

    mergi72
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables read-only file-management operations from AI assistants, including health checks, connection and folder listings, search, share-link resolution, metadata retrieval, and on-demand document reading.
    MIT