pCloud MCP

A hostable Model Context Protocol server for pCloud. After you deploy it on a public HTTPS URL, Grok, Grokbot iOS, Claude, and other MCP clients can browse, read, write, and share files in your pCloud account.

MCP URL after deploy: https://YOUR_HOST/mcp

What it exposes

Grok iOS and Grokbot talk to your server over HTTPS. Your pCloud token stays on the server. Clients sign in to the connector with a password you set (CONNECTOR_PASSWORD).

Related MCP server: nextcloud-agent

Quick start (local)

git clone https://github.com/rghrb/pcloud-mcp.git
cd pcloud-mcp
npm install
cp .env.example .env
# edit .env: at least PCLOUD_ACCESS_TOKEN or connect via /setup
npm run build
npm start

Open http://127.0.0.1:3847/setup, paste a pCloud access token, then point a local MCP client at http://127.0.0.1:3847/mcp.

Grok and Grokbot iOS cannot use localhost. Deploy with HTTPS, then add https://YOUR_HOST/mcp.

Connect pCloud

Pick one:

A. Paste an access token (fastest)

1. Create an app at pCloud My Apps.

2. Open
   https://my.pcloud.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=token

3. After you approve, the redirect URL fragment contains access_token=....

4. Put that token in PCLOUD_ACCESS_TOKEN, or paste it on /setup.

5. Set PCLOUD_API_HOST=eapi.pcloud.com for EU accounts, api.pcloud.com for US. /setup can auto-detect.

B. OAuth from the server

1. Create an app at pCloud My Apps.

2. Add redirect URI https://YOUR_HOST/setup/callback.

3. Set PCLOUD_CLIENT_ID and PCLOUD_CLIENT_SECRET.

4. Open https://YOUR_HOST/setup and click Connect with pCloud.

pCloud access tokens do not expire until you revoke them.

Host it

The container listens on port 3847 (3000 is a common conflict). Persist /data so OAuth clients and the pCloud token survive restarts. Override with PORT if you need a different one.

Docker Compose

cp .env.example .env
# fill CONNECTOR_PASSWORD, PUBLIC_URL, and pCloud token or app credentials
docker compose up --build -d

# docker-compose.yml is in the repo

Render / Railway / Fly / any Node host

If CONNECTOR_PASSWORD is unset, the server writes a random one to data/connector-password.txt on first start.

PUBLIC_URL is also picked up from RENDER_EXTERNAL_URL, RAILWAY_PUBLIC_DOMAIN, or FLY_APP_NAME when those platforms set them.

Docker

docker build -t pcloud-mcp .
docker run --rm -p 3847:3847 \
  -e PUBLIC_URL=https://YOUR_HOST \
  -e CONNECTOR_PASSWORD='pick-a-long-password' \
  -e PCLOUD_ACCESS_TOKEN='...' \
  -e PCLOUD_API_HOST=eapi.pcloud.com \
  -v pcloud-mcp-data:/data \
  pcloud-mcp

Connect Grok iOS / grok.com

1. Deploy this server with a public https:// URL.

2. Finish /setup so pCloud is connected.

3. On the phone or web: grok.com/connectors → New Connector → Custom.

4. Server URL: https://YOUR_HOST/mcp

5. Sign in with CONNECTOR_PASSWORD (or the generated file in data/connector-password.txt).

Grok discovers OAuth 2.1 + PKCE + dynamic client registration on this server. That is the flow the iOS app expects.

Connect Grokbot iOS

Ask the bot to add a custom remote MCP server at https://YOUR_HOST/mcp, then complete the connect card with the same connector password.

Grok Build / other local agents

Remote:

grok mcp add --transport http pcloud https://YOUR_HOST/mcp

Local stdio (no HTTP, token in the environment):

export PCLOUD_ACCESS_TOKEN=...
export PCLOUD_API_HOST=eapi.pcloud.com   # if EU
grok mcp add pcloud -- node /path/to/pcloud-mcp/dist/index.js --stdio

Auth modes

• oauth (default, use this for Grok / Grokbot iOS) — unauthenticated /mcp returns 401 plus OAuth metadata. Clients register themselves and you approve with the connector password.

• bearer — require Authorization: Bearer $MCP_AUTH_TOKEN. Useful for Grok Build headers.

• none — open /mcp. Only use this behind something else that already authenticates, or on a secret URL you accept as the secret.

Development

npm install
npm run dev

npm run build
npm start

License

MIT