Metadata-Version: 2.4
Name: axross-headless-mcp
Version: 0.15.179
Summary: axross's headless MCP server: file tools on the local disk and on SFTP, SMB, WebDAV, S3 and more for any MCP client, over stdio or HTTP - without Qt
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/c0decave/axross-headless-mcp
Project-URL: Source, https://github.com/c0decave/axross-headless-mcp
Project-URL: axross, https://github.com/c0decave/axross
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko<6.0,>=5.0
Requires-Dist: cryptography>=50.0.0
Requires-Dist: jsonschema>=4.21
Requires-Dist: keyring>=25.0
Requires-Dist: PySocks>=1.7
Provides-Extra: images
Requires-Dist: Pillow>=13.0.0; extra == "images"
Provides-Extra: smb
Requires-Dist: smbprotocol>=1.13; extra == "smb"
Provides-Extra: webdav
Requires-Dist: requests>=2.33.0; extra == "webdav"
Requires-Dist: defusedxml>=0.7; extra == "webdav"
Provides-Extra: s3
Requires-Dist: boto3>=1.28; extra == "s3"
Provides-Extra: azure
Requires-Dist: azure-storage-blob>=12.19; extra == "azure"
Requires-Dist: azure-storage-file-share>=12.15; extra == "azure"
Provides-Extra: onedrive
Requires-Dist: msal>=1.26; extra == "onedrive"
Requires-Dist: requests>=2.33.0; extra == "onedrive"
Provides-Extra: gdrive
Requires-Dist: google-api-python-client>=2.100; extra == "gdrive"
Requires-Dist: google-auth-oauthlib>=1.1; extra == "gdrive"
Requires-Dist: google-auth-httplib2>=0.2; extra == "gdrive"
Provides-Extra: dropbox
Requires-Dist: dropbox>=12.0; extra == "dropbox"
Provides-Extra: winrm
Requires-Dist: pywinrm>=0.4; extra == "winrm"
Provides-Extra: wmi
Requires-Dist: impacket>=0.11; extra == "wmi"
Provides-Extra: exchange
Requires-Dist: exchangelib>=5.0; extra == "exchange"
Provides-Extra: adb
Requires-Dist: adb-shell[usb]>=0.4; extra == "adb"
Provides-Extra: archive
Requires-Dist: py7zr>=1.1.3; extra == "archive"
Requires-Dist: rarfile>=4.0; extra == "archive"
Requires-Dist: backports.zstd>=1.0; python_version < "3.14" and extra == "archive"
Provides-Extra: tftp
Requires-Dist: tftpy>=0.8; extra == "tftp"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: mongo
Requires-Dist: pymongo>=4.18.3; extra == "mongo"
Provides-Extra: git
Requires-Dist: dulwich>=1.2.9; extra == "git"
Requires-Dist: urllib3>=2.8.0; extra == "git"
Provides-Extra: dns
Requires-Dist: dnspython>=2.9.0; extra == "dns"
Provides-Extra: magic
Requires-Dist: puremagic>=1.20; extra == "magic"
Provides-Extra: encoding
Requires-Dist: chardet>=5.2; extra == "encoding"
Provides-Extra: snmp
Requires-Dist: pysnmp>=6.2; extra == "snmp"
Provides-Extra: ldap
Requires-Dist: ldap3>=2.9; extra == "ldap"
Provides-Extra: metadata
Requires-Dist: pypdf>=6.21.4; extra == "metadata"
Provides-Extra: all
Requires-Dist: Pillow>=13.0.0; extra == "all"
Requires-Dist: smbprotocol>=1.13; extra == "all"
Requires-Dist: requests>=2.33.0; extra == "all"
Requires-Dist: defusedxml>=0.7; extra == "all"
Requires-Dist: boto3>=1.28; extra == "all"
Requires-Dist: azure-storage-blob>=12.19; extra == "all"
Requires-Dist: azure-storage-file-share>=12.15; extra == "all"
Requires-Dist: msal>=1.26; extra == "all"
Requires-Dist: google-api-python-client>=2.100; extra == "all"
Requires-Dist: google-auth-oauthlib>=1.1; extra == "all"
Requires-Dist: google-auth-httplib2>=0.2; extra == "all"
Requires-Dist: dropbox>=12.0; extra == "all"
Requires-Dist: adb-shell[usb]>=0.4; extra == "all"
Requires-Dist: py7zr>=1.1.3; extra == "all"
Requires-Dist: rarfile>=4.0; extra == "all"
Requires-Dist: tftpy>=0.8; extra == "all"
Requires-Dist: psycopg[binary]>=3.1; extra == "all"
Requires-Dist: redis>=5.0; extra == "all"
Requires-Dist: pymongo>=4.18.3; extra == "all"
Requires-Dist: dulwich>=1.2.9; extra == "all"
Requires-Dist: urllib3>=2.8.0; extra == "all"
Requires-Dist: dnspython>=2.9.0; extra == "all"
Requires-Dist: puremagic>=1.20; extra == "all"
Requires-Dist: chardet>=5.2; extra == "all"
Requires-Dist: pysnmp>=6.2; extra == "all"
Requires-Dist: ldap3>=2.9; extra == "all"
Requires-Dist: pypdf>=6.21.4; extra == "all"
Dynamic: license-file

<!-- mcp-name: io.github.c0decave/axross-headless-mcp -->
# axross-headless-mcp

axross's headless MCP server: file tools on the local disk and on SFTP, SMB, WebDAV, S3 and more for any MCP client, over stdio or HTTP - without Qt.

The MCP (Model Context Protocol) server of [axross](https://github.com/c0decave/axross)
on its own: an LLM client - Claude Desktop, Claude Code, Cursor, VS Code, any MCP client -
lists, reads, searches and hashes files on this machine and on axross's remote
connections, and with `--mcp-write` writes them. No GUI and no Qt: it runs on a server,
in a container or in CI.

- **File tools** (always on, read-only): `list_dir`, `stat`, `read_file`, `checksum`,
  `search`, `walk`, `recursive_checksum`, `grep`, `list_versions`, `open_version_read`,
  and `preview` (image thumbnails; with the `images` extra, which brings Pillow).
- **Write tools** (`--mcp-write --mcp-root DIR`): `write_file`, `mkdir`, `remove`,
  `rename`, `copy`, `bulk_copy`, `symlink`, `hardlink`, `chmod`.
- **Capability groups** (`--mcp-tools GROUP,...` or `all`): metadata, duplicates,
  packer, archive, crypto, index, filetype, transfer, remote (axross's saved
  connection profiles as further backends), exec (`--mcp-allow-exec`), agent,
  extensions.
- Every path is confined to `--mcp-root` (default: your home folder); secret files
  (SSH and GnuPG private keys, tokens) are refused unless `--mcp-allow-secret-reads`.

The protocol: MCP 2025-11-25, 2025-06-18 and 2024-11-05 (the client's version is
answered when it is one of them), tool annotations (read-only, destructive,
idempotent, open-world), structured results with output schemas, progress,
cancellation, logging and `axross://` resources. Long jobs run in the background
through axross's own `axross/tasks/start` / `status` / `cancel` / `list`. A file
name that is not UTF-8 is shown with U+FFFD and comes with its raw bytes
(`name_b64`, `path_b64`); every path argument takes them back (`path_b64`, ...).
The audit trail (what each tool did or refused) goes to stderr and to the log.

### Install

```sh
pipx install axross-headless-mcp                  # or: pip install axross-headless-mcp
pipx install 'axross-headless-mcp[all]'           # with every remote protocol and format
axross-headless-mcp --version
axross-headless-mcp --mcp-list-tools --mcp-tools all   # what it would serve, as JSON
```

The extras are axross's: `smb`, `webdav`, `s3`, `azure`, `onedrive`, `gdrive`,
`dropbox`, `winrm`, `wmi`, `exchange`, `adb`, `archive`, `tftp`, `postgres`, `redis`,
`mongo`, `git`, `dns`, `magic`, `encoding`, `snmp`, `ldap`, `metadata`, plus `images`
(Pillow); `all` holds what axross's own `all` holds (not `winrm`, `wmi`, `exchange`)
plus `images`. SFTP / SSH (paramiko) is always there.

### Connect a client (stdio)

Claude Code:

```sh
claude mcp add axross -- axross-headless-mcp --mcp-root ~/projects --mcp-tools all
```

Claude Desktop, Cursor, VS Code and the like (`claude_desktop_config.json`,
`.cursor/mcp.json`, ...):

```json
{
  "mcpServers": {
    "axross": {
      "command": "axross-headless-mcp",
      "args": ["--mcp-root", "/home/me/projects", "--mcp-tools", "all"]
    }
  }
}
```

Add `--mcp-write` for the write tools (it needs an explicit `--mcp-root`).
`uvx axross-headless-mcp ...` works as the command as well, without installing first.

### Over HTTP

```sh
axross-headless-mcp --mcp-http 127.0.0.1:7331 --mcp-root ~/projects --mcp-tools all
# prints a bearer token (or set AXROSS_MCP_HTTP_TOKEN); the endpoint is
# http://127.0.0.1:7331/messages (streamable HTTP, Mcp-Session-Id, SSE)
```

A client sends `Authorization: Bearer <token>`. Anything but loopback needs mTLS:
`--mcp-cert server.pem --mcp-key server-key.pem --mcp-ca clients-ca.pem`.
`--mcp-allow-scripts` and `--mcp-allow-secret-reads` are stdio-only.

### Docker

```sh
docker run -i --rm -v "$PWD:/data" ghcr.io/c0decave/axross-headless-mcp:latest     --mcp-server --mcp-root /data --mcp-tools all
```

### Settings

The server reads axross's settings (`~/.config/axross`): the saved connection
profiles of the `remote` group (credentials from the system keyring), the metadata
and duplicate indexes, the security mode. The log goes to
`~/.local/state/axross/logs/axross.log` (`--debug` / `-v`: also stderr; stdout is the
protocol's).

Full reference: [docs/MCP.md](https://github.com/c0decave/axross/blob/main/docs/MCP.md)
and the tool catalogue [docs/mcp-tools.json](https://github.com/c0decave/axross/blob/main/docs/mcp-tools.json).
Setup steps for AI agents (Cline and others):
[llms-install.md](https://github.com/c0decave/axross-headless-mcp/blob/main/llms-install.md).

It is the same code as in [axross](https://github.com/c0decave/axross), written out by
axross's `scripts/export_standalone.py mcp`; it reads axross's settings
(`~/.config/axross`) and axross's saved connection profiles.

## Install and run

```sh
pip install axross-headless-mcp      # or, from this folder: pip install .
axross-headless-mcp
```

## Tests

```sh
python -m pytest tests
```

## Licence

Apache-2.0, as axross.
