Hello World MCP Server

A simple example of a Model Context Protocol (MCP) server that demonstrates basic functionality with greeting tools.

Quick Start

1. Install dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   Choose one of three transport methods:

   # For MCP clients (Claude Desktop, Cursor) - stdio transport
   python run_stdio.py
   
   # For HTTP/REST API testing with curl
   python run_http.py
   
   # For SSE transport (web clients)
   python run_sse.py
   

3. Test the server:

   # Test the tools without a client
   python test_server.py
   
   # Test with HTTP API and curl
   python run_http.py
   # Then: curl http://localhost:8000/tools
   

Features

This server provides:

• 4 tools for creating and managing greetings
• 1 resource for greeting templates
• 1 prompt for generating greetings

Documentation

See how-to-run-mcp.md for detailed instructions on:

• Running the server locally
• Testing with various methods
• Integrating with Claude Desktop
• Troubleshooting common issues

Project Structure

hello-mcp/
├── hello_server.py              # Main MCP server implementation
├── test_server.py               # Test script for tools
├── run_stdio.py                 # stdio transport for MCP clients (Claude Desktop, Cursor)
├── run_http.py                  # HTTP API wrapper for curl testing
├── run_sse.py                   # SSE transport for web clients
├── requirements.txt             # Python dependencies
├── Dockerfile                   # Docker container configuration
├── .dockerignore               # Docker ignore file
├── how-to-run-mcp.md           # Detailed setup and testing guide
├── claude_desktop_config_example.json  # Example Claude Desktop configuration
├── README.md                    # This file
└── CLAUDE.md                    # Claude Code guidance file

Transport Methods

This server can run in three different modes:

1. stdio transport (run_stdio.py) - For MCP clients like Claude Desktop and Cursor
2. HTTP transport (run_http.py) - REST API for testing with curl commands
3. SSE transport (run_sse.py) - Server-Sent Events for web clients (requires MCP-compatible web client)

Docker Support

Building the Docker Image

# Build the Docker image
docker build -t hello-mcp .

Running with Docker

# Run HTTP transport (default) - for curl testing
docker run -p 8000:8000 hello-mcp

# Run stdio transport (for MCP clients)
docker run -it hello-mcp python run_stdio.py

# Run SSE transport (for web clients)
docker run -p 8000:8000 hello-mcp python run_sse.py

# Run direct testing
docker run hello-mcp python test_server.py

Testing the Dockerized Server

Once running the HTTP transport container:

# Test the API
curl http://localhost:8000/tools

# Call a tool
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "say_hello", "arguments": {"name": "Docker"}}'

Development with Docker

# Mount source code for development
docker run -p 8000:8000 -v $(pwd):/app hello-mcp

# Interactive shell for debugging
docker run -it hello-mcp /bin/bash

Available Tools

1. say_hello(name) - Basic greeting
2. get_greeting_info() - Server information
3. create_custom_greeting(name, type, include_time) - Customized greetings
4. list_available_greetings() - List greeting types

License

This is an example project for learning MCP.