Metadata-Version: 2.5
Name: mcp-pcloud-crunchtools
Version: 2.1.0
Summary: Secure MCP server for pCloud cloud storage
Project-URL: Homepage, https://github.com/crunchtools/mcp-pcloud
Project-URL: Issues, https://github.com/crunchtools/mcp-pcloud/issues
Author: crunchtools.com
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: cloud-storage,mcp,model-context-protocol,pcloud
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: fastmcp<3.0,>=2.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# mcp-pcloud-crunchtools

<!-- mcp-name: io.github.crunchtools/pcloud -->

Secure MCP server for [pCloud](https://www.pcloud.com/) cloud storage. Browse, search, read, and manage files and folders in a pCloud account through the Model Context Protocol.

Authentication is token-based, OAuth preferred. pCloud accounts with two-factor authentication enabled cannot be accessed with a username and password, and password-derived tokens travel in the URL query string. This server never derives a credential from a password and never puts one in a URL.

## Installation

```bash
# uvx (zero-install)
uvx mcp-pcloud-crunchtools

# PyPI
pip install mcp-pcloud-crunchtools

# Container
podman run quay.io/crunchtools/mcp-pcloud
```

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `PCLOUD_ACCESS_TOKEN` | one of | OAuth access token — sent as an `Authorization: Bearer` header |
| `PCLOUD_AUTH_TOKEN` | one of | pCloud session token — sent in a POST body |
| `PCLOUD_API_HOST` | no | `api.pcloud.com` (default) or `eapi.pcloud.com` for EU accounts |

At least one credential is required. When both are set, the OAuth token wins.

Every credential variable also accepts a `_FILE` form (`PCLOUD_ACCESS_TOKEN_FILE`, `PCLOUD_AUTH_TOKEN_FILE`) pointing at a file that holds the value. The `_FILE` form takes precedence and is preferred for container deployments — it works with podman secrets, Kubernetes secret volumes, and systemd `LoadCredential=`. The server warns (but does not fail) if the file is group- or world-readable.

### Which token do I have?

Create an OAuth access token at [pCloud my_apps](https://docs.pcloud.com/my_apps/). If you only have the token the pCloud desktop client stores, that is a *session* token: pCloud rejects it as an `access_token` with `result 2094`, so set it as `PCLOUD_AUTH_TOKEN` instead. Both carry the same authority over the account — protect them identically.

### Claude Code

```bash
claude mcp add mcp-pcloud-crunchtools \
    --env PCLOUD_ACCESS_TOKEN=your_token_here \
    -- uvx mcp-pcloud-crunchtools
```

## Transports

```bash
mcp-pcloud-crunchtools                                    # stdio (default)
mcp-pcloud-crunchtools --transport sse --port 8028
mcp-pcloud-crunchtools --transport streamable-http --port 8028
```

## Tools

**Folders** — `pcloud_list_folder`, `pcloud_create_folder`, `pcloud_delete_folder`, `pcloud_rename_folder`, `pcloud_copy_folder`

**Files** — `pcloud_get_file_info`, `pcloud_delete_file`, `pcloud_rename_file`, `pcloud_copy_file`, `pcloud_read_text_file`, `pcloud_get_checksum`

**Links** — `pcloud_get_file_link`, `pcloud_create_public_link`

**Search & account** — `pcloud_search`, `pcloud_get_user_info`

`pcloud_create_public_link` publishes a file to anyone holding the returned URL, and `pcloud_get_file_link` returns a time-limited direct download URL. Treat both as credential-issuing operations when building tool allowlists.

## Security

- OAuth token held as a Pydantic `SecretStr`, never logged and scrubbed from error messages
- Token sent in an `Authorization` header, never in a URL
- All arguments validated by Pydantic models with `extra="forbid"`; paths must be absolute and may not contain `..` traversal segments
- TLS certificate validation always on, 30s request timeout, 10 MB response ceiling
- No filesystem access, shell execution, or code evaluation

## Development

```bash
uv sync
uv run ruff check src tests
uv run mypy src
uv run pytest -v
gourmand --full .
podman build -f Containerfile .
```

## License

AGPL-3.0-or-later
