local-tools-mcp-server

A minimal, production-ready MCP server that gives AI assistants access to local file system tools — file search, directory listing, system info, and file metadata.

Built for WorkBuddy and any MCP-compatible client.

Tools

Tool	Description
localtools_search_files	Search files by name pattern / extension with recursive depth control
localtools_system_info	OS, CPU, memory, uptime, user, Node.js version
localtools_list_directory	List directory contents with pagination and hidden-file toggle
localtools_get_file_info	File/directory metadata + text file preview (first 1000 bytes)

All tools are read-only. No files are ever created, modified, or deleted.

Quick Start

Prerequisites

• Node.js >= 18
• npm >= 9

Install & Build

git clone https://github.com/YOUR_USERNAME/local-tools-mcp-server.git
cd local-tools-mcp-server
npm install
npm run build

Configure in WorkBuddy

Add to ~/.workbuddy/mcp.json:

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["E:/path/to/local-tools-mcp-server/dist/index.js"]
    }
  }
}

Then activate the connector in WorkBuddy's Connector Management page.

Configure in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["/path/to/local-tools-mcp-server/dist/index.js"]
    }
  }
}

Usage Examples

Once connected, the AI can use these tools naturally:

"Search my D drive for all .py files, max depth 5"

"How much free memory does my system have?"

"List the contents of my Downloads folder"

"Get info on C:\projects\config.json"

Project Structure

local-tools-mcp-server/
├── src/
│   └── index.ts          # All 4 tools + server entry point (~730 lines)
├── dist/                 # Compiled JS output (gitignored)
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• Runtime: Node.js
• Language: TypeScript
• Validation: Zod
• Protocol: MCP TypeScript SDK
• Transport: stdio (local process, zero network config)

Security

• All file system access is read-only
• Paths are resolved and validated before any operation
• Permission errors are caught and reported gracefully
• No external dependencies beyond the MCP SDK and Zod

License

MIT