Filesystem Watcher

PyPI PyPI Downloads License: Apache 2.0 Python 3.10+

filesystemwatcher-mcp lets your AI coding agent (Gemini, Claude, Cursor, Copilot, etc.) watch directories for live file-system changes. It acts as a Model Context Protocol (MCP) server, giving your agent event-driven access to file creations, modifications, deletions, and moves — without busy-polling.

Key features

• Event-driven file watching: Uses Watchdog for cross-platform native OS events (inotify, FSEvents, ReadDirectoryChangesW).
• Safe by design: Blocks watching system-critical paths on Windows, macOS, and Linux. Strict path guardrails are enforced server-side.
• Flexible filtering: Filter events by file extension, glob pattern, or event type (created, modified, deleted, moved).
• Debounced events: Rapid successive events on the same file are coalesced over a 500 ms window — no duplicate noise.
• Consume-once semantics: poll_events drains the queue, making it easy to integrate into agent loops.
• Explicit error surfacing: All failure modes (permission denied, OS backend crash, watch limit) return structured {"success": false, "error": "..."} responses rather than crashing silently.

Requirements

• Python 3.10 or newer.
• uv (recommended) or pip.

Getting started

Add the following config to your MCP client:

{
  "mcpServers": {
    "filesystemwatcher": {
      "command": "uv",
      "args": ["run", "python", "src/server.py"]
    }
  }
}

[!NOTE] Make sure you have cloned the repository and installed dependencies (uv sync) before pointing your MCP client at the server.

MCP Client configuration

{
  "mcpServers": {
    "filesystemwatcher": {
      "command": "uv",
      "args": ["run", "python", "src/server.py"]
    }
  }
}

claude mcp add filesystemwatcher --scope user uv run python src/server.py

gemini mcp add filesystemwatcher uv run python src/server.py

Your first prompt

Enter the following prompt in your MCP client to check if everything is working:

Watch my home directory for any new file creations and tell me when something appears.

Your agent should call watch_directory and then periodically call poll_events to report changes.

Tools

• File system watching (4 tools)
  • watch_directory
  • poll_events
  • list_active_watches
  • unwatch

watch_directory

Start watching a directory for file system events. Returns a watch_id used to identify this watch session.

Error responses — on failure success is false and error explains why:

poll_events

Drain and return queued file system events (consume-once semantics).

If watch_id is provided but does not match any active watch, the response includes a warning field to prevent agents from silently spinning on a stale ID:

{
  "count": 0,
  "events": [],
  "warning": "No active watch found with id 'abc-123'. Use list_active_watches to see current watch IDs."
}

list_active_watches

Return a summary of all currently active watches.

unwatch

Stop and remove a watch by watch_id.

Configuration

The server currently has no command-line flags; all configuration is done via the tool arguments at runtime.

You can inspect available tools interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector mcp dev src/server.py

Safety guardrails

The server blocks watching dangerous system paths:

Watching C:\Users or /home directly is also blocked; individual user home directories are allowed.

Concurrent watch limit: A maximum of 50 active watches are allowed at any time to prevent exhausting the OS inotify quota. Call unwatch to free a slot before creating a new one.

[!WARNING] The MCP server exposes file-system event data to MCP clients. Avoid watching directories that contain sensitive or personal data you would not want shared with your AI agent.

Debouncing

Events are coalesced over a 500 ms window per (event_type, path) key. Rapid successive events on the same file (e.g. multiple writes during a save) are reported as a single event.

Development

# Clone and install dependencies
git clone https://github.com/your-org/filesystemwatcher-mcp
cd filesystemwatcher-mcp
uv sync

# Run the server directly
uv run python src/server.py

# Run with MCP Inspector
npx @modelcontextprotocol/inspector mcp dev src/server.py

# Run tests
uv run pytest

# Security audit
uv run pip-audit

Known limitations

• Only local file systems are supported; network mounts may not deliver native OS events reliably.
• The server must be restarted to pick up changes to ignored/blocked path configuration.