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

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

Unit Tests

python -m __tests__.main