Hello World MCP Server
A simple example of a Model Context Protocol (MCP) server that demonstrates basic functionality with greeting tools.
Quick Start
-
Install dependencies:
pip install -r requirements.txt -
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 -
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:
- stdio transport (
run_stdio.py) - For MCP clients like Claude Desktop and Cursor - HTTP transport (
run_http.py) - REST API for testing with curl commands - 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
- say_hello(name) - Basic greeting
- get_greeting_info() - Server information
- create_custom_greeting(name, type, include_time) - Customized greetings
- list_available_greetings() - List greeting types
License
This is an example project for learning MCP.