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 toclaude_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 messageread_file: Read contents of a file within allowed pathswrite_file: Write content to fileslist_directory: List files and folders in a directorycreate_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