Universal MCP Server

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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A model-agnostic Model Context Protocol server implementation that works with any compatible AI model or client, allowing tools like file operations to be accessed through the MCP standard.

Related MCP Servers

OpenAI MCP Server
arthurcolle
-
security
F
license
-
quality
A Model Context Protocol server implementation that enables connection between OpenAI APIs and MCP clients for coding assistance with features like CLI interaction, web API integration, and tool-based architecture.
Last updated -
33
Python
MCP Local File Reader
sworddut
-
security
A
license
-
quality
A Model Context Protocol (MCP) server that allows AI models to safely access and interact with local file systems, enabling reading file contents, listing directories, and retrieving file metadata.
Last updated -
13
9
JavaScript
MIT License
AgentModeofficial
agentmode
A
security
F
license
A
quality
An all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.
Last updated -
2
Python
File MCP Server
d-issy
A
security
F
license
A
quality
A Model Context Protocol (MCP) server that enables AI assistants to perform comprehensive file operations including finding, reading, writing, editing, searching, moving, and copying files with security validations.
Last updated -
7
TypeScript

View all related MCP servers