How do I use BTRFS Snapper MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BTRFS Snapper MCP list snapshots for root config" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

BTRFS Snapper MCP

by danielrosehill

Overview Schema Related Servers Score Discussions

Python

Local

BTRFS Snapper MCP

PyPI Built with Claude Code

An MCP (Model Context Protocol) server for managing BTRFS snapshots via Snapper and monitoring BTRFS filesystem health. Exposes two unified tools with action-based dispatch to minimize tool proliferation while providing full snapshot management and disk health monitoring.

Features

Two-tool design: snapper for snapshots, btrfs_health for filesystem monitoring
Full Snapper support: list, create, delete, rollback, cleanup, diff, status
BTRFS health monitoring: usage, device stats, scrub status, balance status
Flexible configuration: Environment variables for cross-system portability
No hardcoded paths: Works with any Snapper configuration and mount points

Related MCP server: Proxmox MCP Server

Installation

From PyPI (recommended)

pip install snapper-mcp

Using uvx (no install required)

uvx snapper-mcp

From source

git clone https://github.com/danielrosehill/BTRFS-Snapper-MCP.git
cd BTRFS-Snapper-MCP
pip install -e .

Configuration

The server is configured via environment variables, making it portable across systems:

Variable	Default	Description
`SNAPPER_MCP_USE_SUDO`	`true`	Set to `false` if user has direct permissions
`SNAPPER_MCP_SNAPPER_PATH`	`snapper`	Path to snapper binary
`SNAPPER_MCP_BTRFS_PATH`	`btrfs`	Path to btrfs binary
`SNAPPER_MCP_SUDO_PATH`	`sudo`	Path to sudo binary
`SNAPPER_MCP_DEFAULT_CONFIG`	`root`	Default snapper config name
`SNAPPER_MCP_DEFAULT_MOUNT`	`/`	Default BTRFS mount point
`SNAPPER_MCP_TIMEOUT`	`60`	Command timeout in seconds

MCP Client Configuration

Claude Code / Claude Desktop

Add to your MCP settings (e.g., ~/.claude/settings.json or Claude Desktop config):

{
  "mcpServers": {
    "btrfs-snapper": {
      "command": "uvx",
      "args": ["snapper-mcp"]
    }
  }
}

With custom configuration

{
  "mcpServers": {
    "btrfs-snapper": {
      "command": "uvx",
      "args": ["snapper-mcp"],
      "env": {
        "SNAPPER_MCP_DEFAULT_CONFIG": "root",
        "SNAPPER_MCP_DEFAULT_MOUNT": "/",
        "SNAPPER_MCP_USE_SUDO": "true"
      }
    }
  }
}

Tools

`snapper` - Snapshot Management

Manages BTRFS snapshots via Snapper.

Actions

Action	Description	Required Parameters
`configs`	List available snapper configurations	-
`list`	Show all snapshots for a config	`config` (optional)
`create`	Create a new snapshot	`config`, `description` (optional)
`delete`	Remove a snapshot by number	`config`, `snapshot_id`
`rollback`	Restore to a previous snapshot	`config`, `snapshot_id`
`cleanup`	Prune snapshots using an algorithm	`config`, `cleanup_algorithm`
`diff`	Show file differences between snapshots	`config`, `snapshot_id`, `snapshot_id_end`
`status`	List changed files between snapshots	`config`, `snapshot_id`, `snapshot_id_end`

Examples

// List configurations
{"action": "configs"}

// List snapshots
{"action": "list", "config": "root"}

// Create snapshot
{"action": "create", "config": "root", "description": "Before system update"}

// Delete snapshot
{"action": "delete", "config": "root", "snapshot_id": 5}

// Rollback (requires reboot)
{"action": "rollback", "config": "root", "snapshot_id": 3}

// Cleanup with algorithm
{"action": "cleanup", "config": "root", "cleanup_algorithm": "number"}

// Compare snapshots
{"action": "diff", "config": "root", "snapshot_id": 1, "snapshot_id_end": 5}

Cleanup algorithms:

number: Keep a fixed number of snapshots
timeline: Keep snapshots based on age (hourly, daily, weekly, monthly, yearly)
empty-pre-post: Remove empty pre/post snapshot pairs

`btrfs_health` - Filesystem Health Monitoring

Monitors BTRFS filesystem health and status.

Actions

Action	Description	Parameters
`usage`	Comprehensive filesystem space usage	`mount_point` (optional)
`devices`	List devices in the BTRFS array	`mount_point` (optional)
`stats`	Device error statistics	`mount_point`, `device` (optional)
`scrub_status`	Status of scrub operation	`mount_point` (optional)
`balance_status`	Status of balance operation	`mount_point` (optional)
`df`	Space allocation by data type	`mount_point` (optional)
`filesystem_show`	Filesystem information	`mount_point` (optional)

Examples

// Check filesystem usage
{"action": "usage", "mount_point": "/"}

// Check for device errors
{"action": "stats", "mount_point": "/"}

// Check scrub status
{"action": "scrub_status", "mount_point": "/"}

// Show data/metadata allocation
{"action": "df", "mount_point": "/"}

// Show filesystem info
{"action": "filesystem_show"}

Prerequisites

Linux with BTRFS filesystem
Snapper installed and configured (for snapshot management)
Python 3.10+
Sudo access (unless running as root or with appropriate permissions)

Installing Snapper

Ubuntu/Debian:

sudo apt install snapper

Fedora/openSUSE:

sudo dnf install snapper
# or
sudo zypper install snapper

Creating Snapper Configs

# For root filesystem
sudo snapper -c root create-config /

# For home partition
sudo snapper -c home create-config /home

Sudo Configuration

For passwordless operation, add to /etc/sudoers.d/btrfs-snapper:

yourusername ALL=(ALL) NOPASSWD: /usr/bin/snapper
yourusername ALL=(ALL) NOPASSWD: /usr/bin/btrfs

Or disable sudo if you have direct permissions:

{
  "env": {
    "SNAPPER_MCP_USE_SUDO": "false"
  }
}

Adapting for Other Systems

Different Snapshot Tools

The architecture can be adapted for other snapshot tools (e.g., Timeshift, ZFS snapshots) by:

Replacing the run_snapper_command() function with your tool's CLI
Adjusting the action handlers for your tool's command syntax
Updating environment variables as needed

Different Filesystems

For ZFS or other filesystems:

Replace run_btrfs_command() with your filesystem's CLI
Update BtrfsAction enum with relevant actions
Implement new handlers for your filesystem's commands

The action-dispatch pattern remains the same regardless of underlying tools.

License

MIT

Available Tools

2 tools

btrfs_healthA

Check BTRFS filesystem health and status. Monitor disk usage, errors, and maintenance operations.

Actions:

usage: Comprehensive filesystem space usage
devices: List devices in the BTRFS array
stats: Device error statistics (corruption, read/write errors)
scrub_status: Status of scrub operation (data integrity check)
balance_status: Status of balance operation (data redistribution)
df: Space allocation by data type (Data, Metadata, System)
filesystem_show: Filesystem information and device list

Current default mount: / Using sudo: True

Examples:

Check usage: action="usage", mount_point="/"
Check for errors: action="stats", mount_point="/"
Scrub status: action="scrub_status", mount_point="/"
Show filesystem: action="filesystem_show"

ParametersJSON Schema

Name	Required	Description
`action`	Yes	The btrfs action: usage (space usage), devices (list devices), stats (error statistics), scrub_status (scrub progress), balance_status (balance progress), df (data/metadata usage), filesystem_show (filesystem info)
`mount_point`	No	BTRFS mount point (e.g., '/', '/home'). Uses default from SNAPPER_MCP_DEFAULT_MOUNT if not specified.
`device`	No	Specific device path for stats action (e.g., '/dev/sda1'). If not specified, uses mount point.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided so description carries full burden. It discloses sudo usage and default mount, but doesn't explicitly state whether actions are read-only or if they can trigger side effects. Actions appear to be monitoring only, but not explicitly confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with bullet points and examples. Front-loaded with purpose. Concise yet comprehensive. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but actions are self-explanatory. Covers key aspects like default mount, sudo requirement, and common examples. Lacks details on error handling or return format, but adequate for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100%, baseline 3. Description adds significant value: explains each action in detail, provides usage examples, and clarifies the 'device' parameter usage. Exceeds baseline with rich context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks BTRFS filesystem health and status, and lists specific actions (usage, devices, stats, etc.). It distinguishes from sibling tool 'snapper' implicitly via different purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides examples for common actions and mentions default mount and sudo usage. However, lacks explicit guidance on when not to use or alternatives beyond sibling name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

snapperA

Manage BTRFS snapshots via Snapper. A unified tool for all snapshot operations.

Actions:

configs: List available snapper configurations
list: Show all snapshots for a config
create: Create a new snapshot (optionally with description)
delete: Remove a snapshot by number
rollback: Restore system to a previous snapshot (requires reboot)
cleanup: Prune snapshots using an algorithm (number, timeline, empty-pre-post)
diff: Show file differences between two snapshots
status: List changed files between two snapshots

Current default config: root Using sudo: True

Examples:

List configs: action="configs"
List snapshots: action="list", config="root"
Create snapshot: action="create", config="root", description="Before update"
Delete snapshot: action="delete", config="root", snapshot_id=5
Compare snapshots: action="diff", config="root", snapshot_id=1, snapshot_id_end=5
Cleanup old snapshots: action="cleanup", config="root", cleanup_algorithm="number"

ParametersJSON Schema

Name	Required	Description
`action`	Yes	The snapper action to perform: list (show snapshots), create (new snapshot), delete (remove snapshot), rollback (restore to snapshot), cleanup (prune by algorithm), diff (compare snapshots), status (show changed files), configs (list available configs)
`config`	No	Snapper configuration name (e.g., 'root', 'home'). Uses default from SNAPPER_MCP_DEFAULT_CONFIG env var if not specified. Use 'configs' action to see available configs.
`snapshot_id`	No	Snapshot number for delete, rollback, or start of range for diff/status
`snapshot_id_end`	No	End snapshot number for diff/status range (e.g., diff between snapshot 5 and 10)
`description`	No	Description for new snapshot (used with 'create' action)
`cleanup_algorithm`	No	Cleanup algorithm: 'number' (keep N snapshots), 'timeline' (keep by age), 'empty-pre-post' (remove empty pre/post pairs)
`sync_after_delete`	No	Sync filesystem after delete operation

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses sudo usage, reboot requirement for rollback, default config, and cleanup algorithms – comprehensive behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections and bulleted actions; front-loaded with purpose. Slightly lengthy due to example redundancy, but still clear and organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all actions, parameters, and operational context (sudo, default config). No output schema, but examples imply outputs. Sufficient for agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. Description provides examples and additional context (e.g., default config from env var) that enhance schema descriptions, justifying above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Manage BTRFS snapshots via Snapper' and lists all eight supported actions. Distinguishes from sibling 'btrfs_health' which likely deals with health checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides examples for each action and mentions default config and sudo usage. Though it doesn't explicitly exclude scenarios for sibling tools, the action list and context make when-to-use clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv0.1.1Jun 11, 2026
- First observedbtrfs_health
- First observedsnapper

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Disambiguation5/5

The two tools have completely distinct purposes: btrfs_health monitors filesystem health, and snapper manages snapshots. There is no overlap in functionality, so an agent can easily distinguish when to use each.

Naming Consistency4/5

Both tool names are descriptive and use a clear style (btrfs_health uses prefix 'btrfs_', snapper uses the application name). While there is no strict pattern like verb_noun, the names are intuitive and consistent in being self-explanatory.

Tool Count2/5

Only two tools for a complex domain like BTRFS management is minimal. Each tool bundles many sub-actions, which could be separate tools for better discoverability. The low count suggests an incomplete surface for tasks like defragmentation or advanced configuration.

Completeness4/5

The tools cover essential BTRFS operations: health monitoring (usage, errors, scrub, balance) and snapshot management (create, delete, rollback, diff, cleanup). Missing are direct balance initiation or defragmentation, but these are covered by status checks, making the set fairly comprehensive for core tasks.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Hive Backup A
io.github.srotzin
Snapshot and restore service for agent state and DID-bound configuration
Autonomous Agents Knowledge & Memory
2
Studex MCP ServerOAuth
io.github.itshivams
Model Context Protocol server for Studex tools, notifications, and profile integrations
Developer Tools
1
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
mcpcheckup A
io.github.fpetitit
Scans remote MCP servers for protocol, security, and TLS issues; exposes scan tools via MCP.
Penetration Testing Security
22

Related MCP Servers

System Information MCP Server
Monitoring OS Automation Observability
dknell
F
license
A
quality
D
maintenance
Provides real-time system metrics and information through a Model Context Protocol interface, enabling access to CPU usage, memory statistics, disk information, network status, and running processes.
Updated a year ago (2025-07-01 03:50 UTC)
7
6
-
Proxmox MCP Server
Virtualization Cloud Platforms
ry-ops
A
license
Not graded
quality
B
maintenance
Enables interaction with Proxmox VE for managing VMs, containers, storage, and cluster resources via natural language through the Model Context Protocol.
Updated 6 days ago (2026-08-31 09:11 UTC)
12
MIT
aha-mcp
Home Automation & IoT
sergiolopezgsiot
A
license
Not graded
quality
C
maintenance
Enables natural language interaction with Home Assistant for managing entities, automations, services, and dashboards via the Model Context Protocol.
Updated a month ago (2026-07-30 20:35 UTC)
237
MIT
DevOps Dashboard MCP Server
Monitoring Observability Command Line
turlockmike
A
license
A
quality
D
maintenance
Enables AI assistants to monitor and manage Linux infrastructure including services, logs, processes, disk, memory, ports, cron, nginx, Docker, and system health checks via the Model Context Protocol.
Updated 5 months ago (2026-04-02 13:31 UTC)
10
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/danielrosehill/BTRFS-Snapper-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

BTRFS Snapper MCP

Features

Installation

From PyPI (recommended)

Using uvx (no install required)

From source

Configuration

MCP Client Configuration

Claude Code / Claude Desktop

With custom configuration

Tools

snapper - Snapshot Management

Actions

Examples

btrfs_health - Filesystem Health Monitoring

Actions

Examples

Prerequisites

Installing Snapper

Creating Snapper Configs

Sudo Configuration

Adapting for Other Systems

Different Snapshot Tools

Different Filesystems

License

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

System Information MCP Server

Proxmox MCP Server

aha-mcp

DevOps Dashboard MCP Server

Latest Blog Posts

MCP directory API

`snapper` - Snapshot Management

`btrfs_health` - Filesystem Health Monitoring