Hello MCP Server
A simple Python MCP (Model Context Protocol) server that provides a greeting tool.
Features
- greet tool: Responds to greeting messages, especially "how are you" with "I am great"
- Dual mode: Runs in stdio mode for local development or HTTP mode for remote access
- Docker ready: Fully containerized with Docker and docker-compose support
Installation
Local Development
- Make sure you have Python installed
- Install the required dependencies:
pip install mcp
Or using uv:
uv add mcp
Docker Deployment
Make sure you have Docker and Docker Compose installed.
Running the Server
Local Development (stdio mode)
Using Python directly:
python server.py
Using uv:
uv run server.py
Local HTTP Mode
To run the server in HTTP mode locally:
$env:TRANSPORT="http"
python server.py
The server will be available at http://localhost:8000/mcp
Docker Deployment
Using Docker Compose (Recommended)
# Build and start the container
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the container
docker-compose down
Using Docker directly
# Build the image
docker build -t hello-mcp-server .
# Run the container
docker run -d -p 8000:8000 --name hello-mcp-server hello-mcp-server
# View logs
docker logs -f hello-mcp-server
# Stop the container
docker stop hello-mcp-server
docker rm hello-mcp-server
Testing the Server
Testing HTTP Endpoint
Once running in HTTP mode, the server exposes an MCP endpoint at:
- Local:
http://localhost:8000/mcp - Container:
http://localhost:8000/mcp
You can connect to it using any MCP client that supports HTTP transport.
With MCP Inspector
npx @modelcontextprotocol/inspector python server.py
With Claude Desktop (Local stdio mode)
Add this configuration to your Claude Desktop config file:
Location: %AppData%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hello-mcp": {
"command": "python",
"args": ["c:\\Users\\ambudhu\\Github\\hello-mcp\\server.py"]
}
}
}
Then restart Claude Desktop and you should see the tool available!
With Claude.ai (HTTP mode)
If you're running the server in HTTP mode (locally or in Docker), you can connect to it from Claude.ai:
- Go to Claude.ai settings
- Add a custom connector
- Enter the URL:
http://localhost:8000/mcp(or your server's public URL)
With VS Code (HTTP mode)
Update your .vscode/mcp.json:
{
"servers": {
"hello-mcp-server": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
With VS Code
The server is already configured in .vscode/mcp.json for use with VS Code's MCP support.
Usage
Once connected to the server, you can use the greet tool:
Tool: greet
Arguments: {"message": "how are you"}
Response: "I am great"
Deployment Options
Running Locally
- Best for: Development and testing
- Transport: stdio or HTTP
- Access: Local machine only
Running in Docker (Local)
- Best for: Testing containerization, isolated environment
- Transport: HTTP
- Access:
http://localhost:8000/mcp
Running in Production
For production deployment, you can:
- Deploy to cloud providers: AWS ECS, Google Cloud Run, Azure Container Apps
- Use Kubernetes: Deploy the container with proper ingress configuration
- Add reverse proxy: Use nginx or Traefik for SSL/TLS termination
- Set up monitoring: Add health checks and logging aggregation
Environment Variables
| Variable | Default | Description |
|---|---|---|
TRANSPORT | stdio | Transport mode: stdio or http |
HOST | 0.0.0.0 | Host to bind to (use 0.0.0.0 for containers) |
PORT | 8000 | Port to listen on |
Project Structure
hello-mcp/
├── server.py # Main MCP server implementation
├── requirements.txt # Python dependencies
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
├── .dockerignore # Docker build exclusions
├── README.md # This file
├── .vscode/
│ └── mcp.json # VS Code MCP configuration
└── .github/
└── copilot-instructions.md # Project instructions
Security Considerations
When deploying in production:
- Use HTTPS: Always use TLS/SSL in production
- Authentication: Consider adding authentication (OAuth, API keys)
- Rate limiting: Implement rate limiting to prevent abuse
- CORS: Configure CORS appropriately for browser-based clients
- Monitoring: Set up proper logging and monitoring
- Secrets: Never commit secrets; use environment variables or secret management