Skip to main content

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 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

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:

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, ...):

{
  "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

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

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 and the tool catalogue docs/mcp-tools.json. Setup steps for AI agents (Cline and others): llms-install.md.

It is the same code as in 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

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

Tests

python -m pytest tests

Licence

Apache-2.0, as axross.

Metadata

Release files for axross-headless-mcp 0.15.179

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for axross-headless-mcp 0.15.179
File Size Uploaded Provenance Actions
axross_headless_mcp-0.15.179.tar.gz 1.9 MB Without provenance Details for axross_headless_mcp-0.15.179.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for axross-headless-mcp 0.15.179
File Interpreter ABI Platform Actions
axross_headless_mcp-0.15.179-py3-none-any.whl Python 3 none any Details for axross_headless_mcp-0.15.179-py3-none-any.whl

Total release size: 4.0 MB

Release files / axross_headless_mcp-0.15.179.tar.gz

Download URL axross_headless_mcp-0.15.179.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
d4ed75a837017d005fd878b805887e4513caa795e92a6a6d4b408a0b19f7d287
BLAKE2b-256 checksum
How to use checksums
de19d5b61c08aa17ba006c3c9640e573ab09b768eca4067856d50a9527215905
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Release files / axross_headless_mcp-0.15.179-py3-none-any.whl

Download URL axross_headless_mcp-0.15.179-py3-none-any.whl
Size 2.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
d8691f6098cccd97e1a5dd8e4990e96abac8d117382d9aac68da68d07335a40f
BLAKE2b-256 checksum
How to use checksums
ca86a2c0bf3fcbcde17afb023fda85251b41dbd38064ba49692b9d700a4f38e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Security for axross-headless-mcp 0.15.179

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.15.179 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page