MCP for Beginners: Build Your First Server in 20 Minutes

# Check that Node.js is installed node --version # → v20.11.0 (or higher) npm --version # → 10.2.4 (or higher) # If Node is not installed, download from https://nodejs.org/

# Create a new folder for your MCP server mkdir mcp-filesystem-server cd mcp-filesystem-server # Initialize a Node.js project npm init -y # Install the official MCP SDK from Anthropic npm install @modelcontextprotocol/sdk # Install development dependencies npm install --save-dev typescript @types/node tsx # Verify installation npm list @modelcontextprotocol/sdk # → @modelcontextprotocol/sdk@1.0.4

# Create tsconfig.json cat > tsconfig.json << 'EOF' { "compilerOptions": { "target": "ES2022", "module": "Node16", "moduleResolution": "Node16", "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"], "exclude": ["node_modules"] } EOF # Create the source folder mkdir src # Create the workspace folder (where Claude can read/write) mkdir workspace

{ "name": "mcp-filesystem-server", "version": "1.0.0", "type": "module", "scripts": { "build": "tsc", "dev": "tsx src/index.ts", "start": "node dist/index.js" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.0.4" }, "devDependencies": { "typescript": "^5.3.3", "@types/node": "^20.11.0", "tsx": "^4.7.0" } }

// src/index.ts import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; import * as fs from "fs/promises"; import * as path from "path"; // Secure folder where Claude can read/write const WORKSPACE_DIR = path.resolve(process.cwd(), "workspace"); // Create the MCP server const server = new Server( { name: "filesystem-server", version: "1.0.0", }, { capabilities: { tools: {}, }, } ); // === TOOL 1: List files in the workspace === server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "list_files", description: "List all files in the workspace folder", inputSchema: { type: "object", properties: {}, }, }, { name: "read_file", description: "Read the content of a file in the workspace", inputSchema: { type: "object", properties: { filename: { type: "string", description: "Name of the file to read (e.g., notes.txt)", }, }, required: ["filename"], }, }, { name: "write_file", description: "Write content to a file in the workspace", inputSchema: { type: "object", properties: { filename: { type: "string", description: "Name of the file to create or overwrite", }, content: { type: "string", description: "Content to write to the file", }, }, required: ["filename", "content"], }, }, ], }; }); // === Handle tool calls === server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case "list_files": { const files = await fs.readdir(WORKSPACE_DIR); return { content: [ { type: "text", text: files.length > 0 ? `Files in workspace: ${files.map((f) => `- ${f}`).join("\n")}` : "The workspace folder is empty.", }, ], }; } case "read_file": { const filename = args.filename as string; const filepath = path.join(WORKSPACE_DIR, filename); // Security: prevent access to files outside workspace if (!filepath.startsWith(WORKSPACE_DIR)) { throw new Error("Access denied outside workspace"); } const content = await fs.readFile(filepath, "utf-8"); return { content: [ { type: "text", text: `Content of ${filename}: ${content}`, }, ], }; } case "write_file": { const filename = args.filename as string; const content = args.content as string; const filepath = path.join(WORKSPACE_DIR, filename); // Security: prevent access to files outside workspace if (!filepath.startsWith(WORKSPACE_DIR)) { throw new Error("Access denied outside workspace"); } await fs.writeFile(filepath, content, "utf-8"); return { content: [ { type: "text", text: `✅ File ${filename} created successfully (${content.length} characters)`, }, ], }; } default: throw new Error(`Unknown tool: ${name}`); } } catch (error: any) { return { content: [ { type: "text", text: `❌ Error: ${error.message}`, }, ], isError: true, }; } }); // === Start the server === async function main() { // Ensure workspace folder exists await fs.mkdir(WORKSPACE_DIR, { recursive: true }); const transport = new StdioServerTransport(); await server.connect(transport); console.error("Filesystem MCP server started ✅"); console.error(`Workspace: ${WORKSPACE_DIR}`); } main().catch((error) => { console.error("Fatal error:", error); process.exit(1); });

# Compile TypeScript to JavaScript npm run build # Verify that dist/index.js was created ls dist/ # → index.js # Test in dev mode (without compiling) npm run dev # → Filesystem MCP server started ✅ # → Workspace: /Users/you/mcp-filesystem-server/workspace # Ctrl+C to stop

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

# Check that the file exists ls workspace/ # → fibonacci.py hello.txt # Read the content cat workspace/fibonacci.py # Expected output: # def fibonacci(n): # if n <= 1: # return n # return fibonacci(n-1) + fibonacci(n-2) # # def test_fibonacci(): # assert fibonacci(0) == 0 # assert fibonacci(1) == 1 # assert fibonacci(10) == 55 # print("✅ All tests pass") # # if __name__ == "__main__": # test_fibonacci()

// Add debug logs in src/index.ts server.setRequestHandler(CallToolRequestSchema, async (request) => { console.error(`[DEBUG] Tool called: ${request.params.name}`); console.error(`[DEBUG] Args: ${JSON.stringify(request.params.arguments)}`); // ... your existing code }); # Rebuild and test npm run build # Logs will appear in Claude Desktop's Developer Console # (View → Developer → Developer Console)