How to Build a Custom MCP Server to Read Local Files with Claude Desktop: Challenges & Solutions

Author(s): Sreekanth Reddy

Originally published on Towards AI.

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-summarizer
cd ~/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 node
import { 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 capability
const 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 path
async 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 statistics
async 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 file
async 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 previews
async function summarizeAllDocuments(dirPath) {
 // Walk directory, find readable files (first 5)
 // Call summarizeDocument on each
 // Return array of previews
}
// Register: Tell Claude what tools are available
server.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 tool
server.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 server
async 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.

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI