Local MCP: Folder/File Counter

This is a simple Model Context Protocol (MCP) server written in Python using the official mcp SDK (specifically FastMCP). It provides a single tool called get_folder_stats that allows LLMs to retrieve the number of files and folders within a given directory, both recursively and non-recursively.

Features

• Non-recursive count (default): Lists and counts files and subdirectories directly inside the target path.
• Recursive count (optional): Counts all files and folders in nested subdirectories when recursive=true.
• Error handling: Returns clear JSON error messages for invalid paths, missing directories, or permission issues.

Setup Instructions

1. Install dependencies: Make sure you have Python installed, then install the required mcp package:

   pip install -r requirements.txt
   

2. Test the server (optional): You can run the server directly to make sure it executes without errors. It will wait for MCP JSON-RPC messages via standard input/output.

   python server.py
   

   (Press Ctrl+C to exit)

Registering with Claude Desktop

To use this tool locally with Claude, you need to add it to your Claude Desktop configuration.

1. Open your Claude Desktop config file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the following entry to your mcpServers object. Replace YOUR_ABSOLUTE_PATH with the full path to where you saved this project.

{
  "mcpServers": {
    "folder_stats": {
      "command": "python",
      "args": [
        "YOUR_ABSOLUTE_PATH/server.py"
      ]
    }
  }
}

Note: You may need to use the absolute path to your Python executable instead of just "python" if Claude has trouble finding it.

Example Tool Usage

Input arguments from Claude:

{
  "path": "./sample_folder",
  "recursive": true
}

Output returned to Claude (JSON string):

{
  "path": "C:\\path\\to\\sample_folder",
  "total_files": 2,
  "total_folders": 1,
  "files": [
    "data.txt",
    "image.png"
  ],
  "folders": [
    "subfolder"
  ],
  "recursive_total_files": 5,
  "recursive_total_folders": 3
}