Skip to main content
Glama
axross-headless-mcp

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.

  • Your files for any MCP client - Claude Desktop, Claude Code, Cursor, VS Code: list, read, search and hash files.

  • Local disk and remote connections - SFTP built in; SMB, WebDAV, S3, Azure, cloud drives, Git, databases as extras.

  • Read-only by default - the write tools only with --mcp-write and an explicit --mcp-root.

  • Confined to one folder - every path stays under --mcp-root; SSH and GnuPG keys and tokens are refused.

  • 50+ tools in groups - metadata, duplicates, archives, crypto, file types, transfers, remote profiles and more.

  • stdio or HTTP - streamable HTTP with a bearer token, mTLS for anything but loopback.

  • No GUI, no Qt - runs on a server, in a container or in CI: pipx, uvx or Docker.

  • Current MCP - 2025-11-25: tool annotations, structured results, progress, cancellation, resources.

  • An audit trail - what each tool did or refused, on stderr and in the log.

  • The same code as axross - axross's settings and saved connection profiles, credentials from the keyring.

Contents

Related MCP server: Filesystem MCP Server

Screenshots

The tools of every group, and a client's tools/call over stdio

The tools of every group, and a client's tools/call over stdio.

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 --mcp-list-tools --mcp-tools all   # what it would serve, as JSON

Connect a client

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

Claude Desktop, Cursor, VS Code and other clients: the JSON configuration. Over HTTP (a bearer token, mTLS off loopback): Over HTTP. In a container:

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

Documentation

Page

What it covers

Extended README

every tool group, the protocol, HTTP, Docker, settings

docs/MCP.md

the full reference of axross's MCP server

docs/mcp-tools.json

the tool catalogue, generated from the manifest

llms-install.md

setup steps for AI agents (Cline and others)

Tests

python -m pytest tests

Licence

Apache-2.0, as axross: the same code, written out by axross's scripts/export_standalone.py. Everything in detail: the extended README.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Stdio MCP server for sandboxed file access — read files, search content, safely edit with checksums, and manage file structure.
      264 npm
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for filesystem operations, enabling reading, writing, editing, moving, and searching files with dynamic directory access control via MCP Roots.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local filesystem MCP server providing constrained file operations (read/write, directory management, search, metadata) within configurable directories, with read-only mode and zero runtime dependencies.
      4 npm
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables any MCP-compatible client to perform filesystem operations — reading, listing, writing, searching, watching directories, and batch processing files — over JSON-RPC 2.0 stdio transport. Includes resource discovery, metrics tracking, and security controls such as allowed roots, size limits, and format allowlists, with a LangGraph agent that accesses files exclusively through MCP.
      6
      -