README.md•5.23 kB
# 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
1. Make sure you have Python installed
2. Install the required dependencies:
```powershell
pip install mcp
```
Or using uv:
```powershell
uv add mcp
```
### Docker Deployment
Make sure you have Docker and Docker Compose installed.
## Running the Server
### Local Development (stdio mode)
**Using Python directly:**
```powershell
python server.py
```
**Using uv:**
```powershell
uv run server.py
```
### Local HTTP Mode
To run the server in HTTP mode locally:
```powershell
$env:TRANSPORT="http"
python server.py
```
The server will be available at `http://localhost:8000/mcp`
### Docker Deployment
#### Using Docker Compose (Recommended)
```powershell
# Build and start the container
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the container
docker-compose down
```
#### Using Docker directly
```powershell
# 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
```powershell
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`
```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:
1. Go to Claude.ai settings
2. Add a custom connector
3. Enter the URL: `http://localhost:8000/mcp` (or your server's public URL)
### With VS Code (HTTP mode)
Update your `.vscode/mcp.json`:
```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:
1. **Deploy to cloud providers**: AWS ECS, Google Cloud Run, Azure Container Apps
2. **Use Kubernetes**: Deploy the container with proper ingress configuration
3. **Add reverse proxy**: Use nginx or Traefik for SSL/TLS termination
4. **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:
1. **Use HTTPS**: Always use TLS/SSL in production
2. **Authentication**: Consider adding authentication (OAuth, API keys)
3. **Rate limiting**: Implement rate limiting to prevent abuse
4. **CORS**: Configure CORS appropriately for browser-based clients
5. **Monitoring**: Set up proper logging and monitoring
6. **Secrets**: Never commit secrets; use environment variables or secret management
## Learn More
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP Documentation](https://modelcontextprotocol.github.io/python-sdk/)