MCP Server - From Scratch

A Model Context Protocol (MCP) server implementation developed from scratch. When I say scratch I literally mean, that the JSON-RPC, STDIO, and server to client connection is written by hand! This is not a simple implementation that uses the @mcp.tool functionality you see online.

This project was created to help me understand the MCP protocol and was carefully modeled after the official MCP server specification.

Project Goals

Simple Architecture: Clean, from-scratch implementation following official MCP specification
Extensible Tools: Easy to add new tools and capabilities
Learning-Focused: Well-documented code to understand MCP internals

Related MCP server: MCP Local File Reader

Architecture

┌─────────────────┐ JSON-RPC ┌─────────────────┐ │ AI Model │ ◄──────────────► │ MCP Server │ │ (Any Provider) │ (stdio) │ (Python) │ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ │ Tools │ │ • File Reader │ │ • File Writer │ │ • Directory Ops │ └─────────────────┘

Quick Start

Running the MCP Server

# Create virtual environment python3 -m venv mcp-venv # Activate virtual environment source mcp-venv/bin/activate # On macOS/Linux # or mcp-venv\Scripts\activate # On Windows

# Install required packages pip install -r requirements.txt

# Test server starts correctly python3 src/mcp_server.py

Integrating with Models

Claude Desktop Config

For Claude Desktop, create or edit the config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following configuration to claude_desktop_config.json:

{ "mcpServers": { "barebones-server": { "command": "{project_path}/mcp-venv/bin/python", "args": ["{project_path}/src/mcp_server.py"], "env": { "PYTHONPATH": "{project_path}/src" } } } }

Demo:

https://github.com/user-attachments/assets/d7e21bb3-bc6d-4b9b-8b7d-ed90f7f004fd

Available Tools

Current Tools

greeting: Returns a greeting message
read_file: Read contents of a file within allowed paths
write_file: Write content to files
list_directory: List files and folders in a directory
create_directory: Create a new directory

Testing

Run with MCP Inspector

# Install MCP Inspector globally npm install -g @modelcontextprotocol/inspector # Run the MCP server with Inspector npx @modelcontextprotocol/inspector \ /{path_to_MCP_projecct}/mcp-venv/bin/python \ /{path_to_MCP_projecct}/src/mcp_server.py