5 min read8 hours ago

–

Background: Why You Need MCP

Claude is powerful, but by default it can’t access your computer’s files. It lives in the cloud and has no idea what’s on your hard drive. This limitation becomes a bottleneck when you want Claude to:

• Analyze your project structure
• Summarize documents in a folder
• Browse your codebase
• Process local files in batch
• Access real-time data on your machine

Enter: Model Context Protocol (MCP)

MCP is a standardized protocol released by Anthropic that bridges this gap. It allows Claude Desktop (the local app) to securely communicate with tools running on your computer. Think of it as giving Claude permission to peek into your file system through a controlled gateway.

What I amBuilding

An MCP server that extends Claude’s capabilities with 4 new tools:

• read_directory — List all files in any folder
• summarize_directory — Get statistics (file types, total size, file counts)
• summarize_document — Preview any text file (code, markdown, etc.)
• summarize_all_documents — Batch preview multiple documents

Once installed, you can ask Claude things like:

“Show me all Python files in my project” “What’s the total size of my Downloads folder?” “Give me a preview of my main.py file”

The Problem: Getting MCP to Work

The journey to a working MCP server is filled with hidden pitfalls. I encountered 3major challenges while building this, plus a critical decision point about which language to use.

Why Node.js, Not Python?

I started with Python but hit three critical blockers:

1. Version Dependency — Python MCP requires 3.10+, many systems use 3.9
2. Manual Protocol Implementation — No official Python SDK caused schema validation errors
3. No Official Support — Anthropic maintains the Node.js SDK; Python is unsupported

Result: I switched to Node.js and fixed everything in minutes.

What I Built

A server with 4 tools:

• read_directory - List files in a path
• summarize_directory - Get file statistics
• summarize_document - Preview a file
• summarize_all_documents - Preview multiple files

Setup

Step 1: Create Project

mkdir -p ~/mcp-servers/directory-summarizercd ~/mcp-servers/directory-summarizer

Step 2: Create package.json

{  "name": "directory-summarizer-mcp",  "version": "1.0.0",  "type": "module",  "dependencies": {    "@modelcontextprotocol/sdk": "^1.0.0"  }}

Step 3: Install Dependencies

npm install

Step 4: Create server.js

Create a new file called server.js in the same directory with the following high-level structure:

#!/usr/bin/env nodeimport { Server } from "@modelcontextprotocol/sdk/server/index.js";import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { readdir, readFile, stat } from "fs/promises";import { resolve, extname } from "path";import { homedir } from "os";// Initialize MCP server with tools capabilityconst server = new Server(  { name: "directory-summarizer", version: "1.0.0" },  { capabilities: { tools: {} } }  // ← Critical: declare tools support);// Tool Implementation 1: readDirectory(path)// Lists files and directories in a given pathasync function readDirectory(path) {  // Resolve path, read directory entries  // Return { files: [], directories: [], file_count, dir_count }}// Tool Implementation 2: summarizeDirectory(path)// Recursively walks directory and returns statisticsasync function summarizeDirectory(path) {  // Walk all subdirectories recursively  // Count files by type, calculate total size  // Return { total_files, total_directories, total_size, file_types }}// Tool Implementation 3: summarizeDocument(filePath)// Returns preview of a document fileasync function summarizeDocument(filePath) {  // Read file content, check if readable type  // Return first 500 chars as preview}// Tool Implementation 4: summarizeAllDocuments(dirPath)// Finds all documents in directory and returns previewsasync function summarizeAllDocuments(dirPath) {  // Walk directory, find readable files (first 5)  // Call summarizeDocument on each  // Return array of previews}// Register: Tell Claude what tools are availableserver.setRequestHandler(ListToolsRequestSchema, async () => {  return {    tools: [      { name: "read_directory", description: "List files in a path", inputSchema: {...} },      { name: "summarize_directory", description: "Get directory stats", inputSchema: {...} },      { name: "summarize_document", description: "Get file preview", inputSchema: {...} },      { name: "summarize_all_documents", description: "Preview all docs", inputSchema: {...} }    ]  };});// Register: Handle when Claude calls a toolserver.setRequestHandler(CallToolRequestSchema, async (request) => {  const { name, arguments: args } = request.params;    // Execute appropriate tool based on name  // Return result as JSON  return {    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]  };});// Start serverasync function main() {  const transport = new StdioServerTransport();  await server.connect(transport);}main().catch(console.error);

What this does:

• Imports MCP SDK and Node.js file utilities
• Creates a server with tools capability (must have this)
• Defines 4 tool functions that read/analyze local files
• Registers tools so Claude Desktop knows what’s available
• Handles tool calls from Claude
• Connects via stdio (standard input/output)

Step 5: Update Claude Desktop Config

Find config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server:

{  "mcpServers": {    "directory-summarizer": {      "command": "node",      "args": ["/Users/YOUR_USERNAME/mcp-servers/directory-summarizer/server.js"]    }  }}

Replace YOUR_USERNAME with your actual username.

Step 6: Restart Claude Desktop

• Force quit completely
• Reopen it
• Now you should see the “directory-summarizer” under “Search and tools”

Testing

In Claude, ask:

• “Show me files in ~/Documents”
• “What’s in my Downloads folder?”
• “Get a preview of this file: /path/to/file.py”

Lessons Learned

1. Use Official SDKs — Don’t implement protocols manually
2. Stdout is Data — No debug prints, only JSON output
3. Declare Capabilities — Tell MCP what your server can do upfront
4. Config Matters — One mismatch breaks everything
5. Start Simple — Test one tool before adding more

Conclusion

Building a custom MCP server seems intimidating at first, but it’s actually straightforward once you understand the core concepts. The six challenges I faced — Python version conflicts, stdout pollution, schema validation, config mismatches, module configuration, and capability declaration — are all solvable with the right approach.

The key takeaway: use the official MCP SDK, not manual protocol implementation. It handles all the complexity so you can focus on building useful tools for Claude.

Once you have a working server like this one, you unlock a new paradigm: Claude becomes a local agent that can deeply understand your codebase, documents, and file systems. This opens doors to:

• Automated code analysis and documentation
• Intelligent file organization and batch processing
• Real-time project insights directly in Claude
• Custom tools tailored to your workflow

The future of AI isn’t just cloud-based; it’s hybrid. Tools like MCP bridge that gap, giving you the power of Claude with the privacy and control of local files.

Now that you understand the challenges and have a working blueprint, go build something amazing. Start small, test often, and iterate. The MCP ecosystem is growing fast, and your custom servers could become valuable contributions to the community.