folderinfo-mcp

folderinfo-mcp

Ultra-simple MCP server for folder exploration.

Tools

• tree: formatted directory tree
• ls: list items in directory
• recursive-ls: recursive listing
• folder-info: markdown report (tree, cwd, file contents)

Parameters (all tools)

Name	Type	Description
dir	string	Target directory (default cwd)
filetype	string[]	Extensions (without dot) to include
excludedFolders	string[]	Regex or glob patterns to exclude folders
excludedFiles	string[]	Regex or glob patterns to exclude files

Usage (Claude Desktop)

Add to config:

{
  "mcpServers": {
    "folderinfo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/folderinfo-mcp/dist/index.js"]
    }
  }
}

Dev:

pnpm install
pnpm run dev

Build & Run:

pnpm run build
pnpm start

Test Tools:

pnpm test

## Global CLI Install / Wrapper

The published binary uses a small ESM wrapper (`bin/folderinfo-mcp.mjs`) with a shebang. This avoids losing the shebang when rebuilding `dist/`.

Install globally (development link):

```bash
pnpm build
pnpm link --global
folderinfo-mcp  # should print: folderinfo-mcp server running

Or via npm after publish:

npm install -g folderinfo-mcp
folderinfo-mcp

If you prefer to reference directly in a Claude config without global install:

{
  "mcpServers": {
    "folderinfo": {
      "command": "node",
      "args": ["/absolute/path/folderinfo-mcp/dist/index.js"]
    }
  }
}

Why a Wrapper?

Because TypeScript outputs ESM files without a shebang, executing dist/index.js directly as a binary (from the package bin field) would fail or silently do nothing on some shells. The wrapper adds:

• Shebang line (#!/usr/bin/env node)
• Stable path resolution to dist/index.js
• Clear error message if startup fails

Troubleshooting

Issue	Cause	Fix
Running folderinfo-mcp does nothing	Old global link cached	Re-run pnpm link --global after build
Permission denied	Missing execute bit	chmod +x bin/folderinfo-mcp.mjs
Not updated after edits	Forgot to rebuild	pnpm build then re-link