Skip to main content
Glama

Minimal MCP

by engineers-hub-ltd-in-house-project
GitHub
JavaScript
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Minimal MCP

A minimal implementation of Model Context Protocol (MCP) server and client for educational and development purposes.

Project Structure

minimal-mcp/ ├── server/ # MCP Server (TypeScript) ├── client/ # MCP Client (Python) └── README.md

Prerequisites

  • Node.js 22+
  • Python 3.13+
  • TypeScript

Server Setup

Install Dependencies

cd server npm install

Build Server

npm run build

Test Server

npm run inspector

Open the URL shown in the terminal (typically http://localhost:6274/) to test the server tools.

Client Setup

Create Virtual Environment

cd client python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

Configure Environment

Create .env file with your OpenAI API key:

echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

Run Client

python client.py

Available Tools

The MCP server provides three tools:

  1. calculate_sum: Adds two numbers
    • Parameters: a (number), b (number)
    • Example: calculate_sum(42, 58) → 100
  2. reverse_string: Reverses a text string
    • Parameters: text (string)
    • Example: reverse_string('Hello MCP') → 'PCM olleH'
  3. get_current_time: Returns current ISO timestamp
    • Parameters: none
    • Example: get_current_time() → '2025-08-24T01:52:39.749Z'

Usage Methods

Method 1: Direct Client Testing

Run the Python client to test all tools:

cd client python client.py

This will automatically:

  1. Connect to the MCP server
  2. Execute all three tools with sample data
  3. Display results

Method 2: Claude Code Integration

Add MCP server to Claude Code configuration:

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

Then use in Claude Code:

Using the minimal-mcp tools: 1. Calculate the sum of 123 and 456 2. Reverse the text "Model Context Protocol" 3. Get the current time

Method 3: MCP Inspector

Use the official MCP inspector for interactive testing:

cd server npm run inspector

Open the URL shown in the terminal to test tools interactively in the browser.

Development

Server Development

cd server npm run watch # Auto-rebuild on changes

Adding New Tools

Edit server/src/index.ts to add new tools:

  1. Add tool definition to the tools array:
{ name: "your_tool_name", description: "Description of what the tool does", inputSchema: { type: "object", properties: { param: { type: "string", description: "Parameter description" } }, required: ["param"] } }
  1. Add tool handler in the CallToolRequestSchema switch case:
case "your_tool_name": const { param } = args as { param: string }; // Your tool logic here return { content: [ { type: "text", text: `Result: ${param}` } ] };
  1. Rebuild the server:
npm run build

Troubleshooting

Permission Denied

chmod +x server/build/index.js

Inspector Port Issues

The inspector automatically finds available ports. If you see different port numbers in the output (e.g., proxy on 6277, web UI on 6274), this is normal. Use the URL shown in the terminal output.

Module Not Found

Check Node.js version and ensure all dependencies are installed:

node --version # Should be 22+ npm install

Architecture

System Overview

Sequence Diagram

Demo

Installation and Setup

Method 1: Claude Code Integration

Add the MCP server directly to Claude Code:

claude mcp add minimal-mcp-server minimal-mcp-server
Method 2: Global npm Installation

Install globally and configure manually:

# Install the package globally npm install -g minimal-mcp-server # Then add to Claude Code configuration manually # (or use other MCP-compatible clients)

Manual configuration for Claude Code:

{ "mcpServers": { "minimal-mcp-server": { "command": "minimal-mcp-server" } } }

Live Test Results

Here are actual test results from Claude Code integration:

1. Calculate Sum
Input: calculate_sum(42, 58) Output: "The sum of 42 and 58 is 100"
2. Reverse String
Input: reverse_string("Hello MCP World") Output: "Reversed text: dlroW PCM olleH"
3. Get Current Time
Input: get_current_time() Output: "Current time: 2025-08-24T02:19:17.244Z"

Python Client Test

You can also test with the included Python client:

cd client python client.py

Example output:

🚀 Initializing MCP agent and connecting to services... ✅ Created 1 new sessions 🧠 Agent ready with tools: calculate_sum, reverse_string, get_current_time 🔧 Tool call: calculate_sum with input: {'a': 42, 'b': 58} 📄 Tool result: The sum of 42 and 58 is 100 🔧 Tool call: reverse_string with input: {'text': 'Hello MCP'} 📄 Tool result: Reversed text: PCM olleH 🔧 Tool call: get_current_time with input: {} 📄 Tool result: Current time: 2025-08-24T02:16:40.654Z

License

MIT

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

A basic educational MCP server that provides simple tools for mathematical calculations, text manipulation, and time retrieval. Designed for learning MCP implementation patterns and development purposes.

  1. Project Structure
    1. Prerequisites
      1. Server Setup
        1. Install Dependencies
        2. Build Server
        3. Test Server
      2. Client Setup
        1. Create Virtual Environment
        2. Install Dependencies
        3. Configure Environment
        4. Run Client
      3. Available Tools
        1. Usage Methods
          1. Method 1: Direct Client Testing
          2. Method 2: Claude Code Integration
          3. Method 3: MCP Inspector
        2. Development
          1. Server Development
          2. Adding New Tools
        3. Troubleshooting
          1. Permission Denied
          2. Inspector Port Issues
          3. Module Not Found
        4. Architecture
          1. System Overview
          2. Sequence Diagram
        5. Demo
          1. Installation and Setup
          2. Live Test Results
          3. Python Client Test
        6. License

          Related MCP Servers

          • FastMCP Calculator Server

            insujeon
            -
            security
            F
            license
            -
            quality
            A server that provides basic mathematical operations (addition, subtraction, multiplication, division, power, square root) through MCP tools for use with AI assistants like Claude.
            Last updated -

          • MCP & Copilot Studio Learning Project

            sayedpfe
            A
            security
            F
            license
            A
            quality
            A comprehensive learning project providing hands-on experience with Model Context Protocol (MCP) server development, featuring calculator and text utility tools for integration with Claude Desktop.
            Last updated -
            1
            • Apple
            • Linux

          • MCPDataAnalytics

            anujpandey2
            -
            security
            F
            license
            -
            quality
            A teaching repository that instructs non-technical users how to create Model Completion Protocol (MCP) servers for data analysis tasks, requiring only basic technical setup and understanding.
            Last updated -

          • MCP Boilerplate Server

            shazaaly
            -
            security
            F
            license
            -
            quality
            A basic MCP server template built with FastMCP that provides simple tools for greeting users, performing math operations, and managing user information. Serves as a starting point for building custom MCP servers with essential functionality examples.
            Last updated -
            4
            • Apple

          View all related MCP servers

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/engineers-hub-ltd-in-house-project/minimal-mcp'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server