MCP Docker Demo

A Model Context Protocol (MCP) server implementation with Docker support and a web-based inspector.

🚀 Quick Start

1. Build the Docker Image

docker build -t rak-greet .

2. Test the Server (Simple Client)

docker run --rm -i rak-greet python client.py

3. Launch Web Inspector (Recommended)

docker run --rm -p 8000:8000 rak-greet python mcp_inspector_web.py

Then open your browser to: http://localhost:8000

📁 Project Structure

mcpdocker-demo/
├── server.py              # MCP server with hello-world tool
├── client.py             # Simple test client
├── mcp_inspector_web.py  # Web UI for testing
├── Dockerfile            # Container configuration
└── requirements.txt      # Python dependencies

🔧 What's Inside

MCP Server (server.py)

• Implements a simple "hello-world" tool

• Accepts a greeting and returns it with " World!" appended

• Runs over stdio transport

• Includes debug logging

Web Inspector (mcp_inspector_web.py)

• Beautiful web interface for testing MCP servers

• Lists available tools

• Shows tool schemas

• Interactive testing with real-time results

• Built with FastAPI

Simple Client (client.py)

• Command-line MCP client

• Connects to server via stdio

• Tests the hello-world tool

🛠️ Development

Local Development (without Docker)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run server
python server.py

# In another terminal, run client
python client.py

Run Web Inspector Locally

uvicorn mcp_inspector_web:app --host 0.0.0.0 --port 8000 --reload

📝 API Reference

Hello World Tool

Name: hello-world

Description: A simple tool that returns a greeting.

Input Schema:

{
  "type": "object",
  "properties": {
    "greeting": {
      "type": "string",
      "description": "The greeting to return"
    }
  },
  "required": ["greeting"]
}

Example:

Input:  {"greeting": "Hello"}
Output: "Hello World!"

🐳 Docker Commands

# Build image
docker build -t rak-greet .

# Run server
docker run --rm -i rak-greet python server.py

# Run client
docker run --rm -i rak-greet python client.py

# Run web inspector
docker run --rm -p 8000:8000 rak-greet python mcp_inspector_web.py

🔍 Troubleshooting

"Connection closed" Error

This usually means the server failed to start. Check:

1. Python version (should be 3.11+)

2. All dependencies installed

3. Server logs for errors

Port Already in Use

If port 8000 is busy:

docker run --rm -p 8001:8000 rak-greet python mcp_inspector_web.py

Then open: http://localhost:8001

📚 Learn More

• Model Context Protocol Documentation

• MCP Specification

• MCP Python SDK

🤝 Contributing

Feel free to open issues or submit pull requests!

📄 License

MIT License - feel free to use this code however you'd like!