RayenMalouche/Folder-Structure-MCP-Server

Folder Structure MCP Server

A lightweight, fast Model Context Protocol (MCP) server that generates beautiful, readable tree-style folder structures with file sizes and smart file type descriptions — perfect for giving LLMs (like Claude, Cursor, Windsurf, etc.) full context about your project's layout.

Ideal for use with Claude Desktop, Cursor, or any MCP-compatible client.

my-project/
├── src/
│   ├── main/
│   │   ├── java/                  # Java source
│   │   └── resources/             # Config files
│   └── test/                      # Test sources
├── pom.xml                        # Maven POM
├── README.md                      # Markdown doc
└── .gitignore

Features

• Generates clean tree view of any directory
• Shows human-readable file sizes (KB, MB, GB...)
• Automatically adds helpful descriptions for 50+ common file types
• Respects .gitignore-style hidden files (optional)
• Configurable max depth
• Supports both STDIO and HTTP/SSE transport modes
• Built with Spring Boot + Jetty + official MCP SDK

Quick Start (Recommended for Claude Desktop)

1. Build the JAR

git clone https://github.com/your-username/folder-structure-mcp-server.git
cd folder-structure-mcp-server
mvn clean package -DskipTests

This creates two JARs:

• target/server-0.0.1-SNAPSHOT.jar → regular JAR
• target/server-0.0.1-SNAPSHOT-shaded.jar → fat/uber JAR (recommended)

The shaded JAR contains all dependencies and is easiest to use.

2. Use with Claude Desktop (or any MCP client)

Add this to your mcp.json or Claude's tools config:

{
  "mcpServers": {
    "folder-structure": {
      "command": "java",
      "args": [
        "-jar",
        "C:\\path\\to\\your\\folder-structure-mcp-server\\target\\server-0.0.1-SNAPSHOT-shaded.jar",
        "--stdio"
      ]
    }
  }
}

Replace the path with wherever you placed the shaded JAR.

Now you can ask Claude things like:

“Show me the full folder structure of my current project with file descriptions”

or

“generate-folder-structure this project, include hidden files, max depth 20”

Tool Usage

Tool Name: generate-folder-structure

Parameters:

Example calls in chat:

Please run generate-folder-structure on the current project directory with showHidden=true

generate-folder-structure /home/user/my-app maxDepth=10

Running Manually

Option 1: STDIO mode (for MCP clients)

java -jar target/server-0.0.1-SNAPSHOT-shaded.jar --stdio

Option 2: HTTP mode (for testing or remote access)

java -jar target/server-0.0.1-SNAPSHOT-shaded.jar
# → Starts on http://localhost:45451

Or streamable HTTP mode:

java -jar target/server-0.0.1-SNAPSHOT-shaded.jar --streamable-http
# MCP endpoint: http://localhost:45451/message

📸 Screenshot – Claude Desktop using Folder Structure MCP Server

Here’s a preview of Claude Desktop connected to the Folder Structure MCP Server, generating a full project tree directly inside the chat interface.

The screenshot shows the generate-folder-structure tool running successfully, producing a clean visual folder tree for a Python game project.

Supported File Descriptions (partial)

(and many more!)

Development

# Run with hot reload (via Spring Boot)
mvn spring-boot:run

# Build shaded JAR
mvn clean package -DskipTests

Requirements

• Java 21+
• Maven (for building)

License

MIT © 2025 Rayen Malouche

Made to help AI understand your codebase better — one tree at a time 🌳