Skip to main content
Glama
guilleyalo

Demo MCP Server

by guilleyalo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Demo MCP Server

A minimal FastMCP Python server demonstrating basic MCP (Model Context Protocol) functionality with a simple cowsay tool.

Features

  • FastMCP Server: Simple MCP server implementation

  • Cowsay Tool: Generate ASCII art of a cow saying custom messages

  • Environment Configuration: .env file support with Pydantic settings

  • Docker Support: Full Docker and docker-compose setup

  • Testing: Basic unit tests with pytest

  • KISS Principle: Keep It Simple, focused implementation

Related MCP server: MCP Example Simple Server

Quick Start

Local Development

  1. Install dependencies:

    make install-dev

  2. Run the server (http mode on port 8005):

    make run-http

  3. Run tests:

    make test

Docker

  1. Build and run:

    make docker-build
make docker-run

  2. For HTTP transport:

    make docker-run-http

Project Structure

my-mcp-server/
├── src/
│   ├── config/
│   │   └── settings.py          # Environment configuration
│   └── mcp/
│       ├── __main__.py          # Entry point
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           └── cowsay.py        # Cowsay MCP tool
├── tests/                       # Unit tests
├── .env.example                 # Environment variables template
├── docker-compose.yml           # Docker compose configuration
├── Dockerfile                   # Docker container definition
├── Makefile                     # Common commands
└── pyproject.toml              # Python project configuration

Available Tools

cowsay

Generate ASCII art of a cow saying a message.

Parameters:

  • message (str): The message for the cow to say

  • cow (str, optional): The type of cow to use (default: "default")

Example:

result = await cowsay("Hello, World!")

Output:

 _______________
< Hello, World! >
 ---------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Configuration

The server uses environment variables for configuration. Copy .env.example to .env and customize:

cp .env.example .env

Available Settings

Variable

Default

Description

APP_NAME

"Demo MCP Server"

Application name

LOG_LEVEL

"INFO"

Logging level

MCP_TRANSPORT

"stdio"

MCP transport method

MCP_HOST

"127.0.0.1"

Host for HTTP transport

MCP_PORT

"8000"

Port for HTTP transport

MAX_MESSAGE_LENGTH

"500"

Maximum cowsay message length

Usage with MCP Clients

Claude Desktop

Add to your MCP settings:

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/my-mcp-server"
    }
  }
}

Command Line

# STDIO transport (default)
python -m src.mcp --transport stdio

# HTTP transport
python -m src.mcp --transport http --port 8000

# Help
python -m src.mcp --help

Development

Available Make Commands

make help              # Show all available commands

# Development
make install           # Install dependencies
make install-dev       # Install with dev dependencies
make test             # Run tests
make test-verbose     # Run tests with verbose output

# Running
make run              # Run server locally (STDIO)
make run-http         # Run server locally (HTTP)
make health           # Check server health

# Docker
make docker-build     # Build Docker image
make docker-run       # Run in Docker (STDIO)
make docker-run-http  # Run in Docker (HTTP)
make docker-stop      # Stop containers
make docker-clean     # Clean containers and images

# Cleanup
make clean            # Clean build artifacts

Testing

# Run all tests
make test

# Run with coverage
python -m pytest --cov=src --cov-report=html

# Run specific test
python -m pytest tests/test_cowsay.py -v

Adding New Tools

  1. Create a new tool file in src/mcp/tools/

  2. Implement the tool using FastMCP patterns

  3. Register it in src/mcp/server.py

  4. Add tests in tests/

Example tool structure:

from fastmcp.tools import Tool

def create_my_tool() -> Tool:
    async def my_tool(param: str) -> dict:
        # Tool implementation
        return {"success": True, "result": param}
    
    return Tool(
        name="my_tool",
        description="Description of my tool",
        func=my_tool,
    )

Docker

Building

docker-compose build

Running

STDIO mode (for MCP clients):

docker-compose up demo-mcp-server

HTTP mode (for testing):

docker-compose --profile http up demo-mcp-http

Environment Variables in Docker

Create a .env file or set environment variables in docker-compose.yml:

environment:
  - APP_NAME=My Custom MCP Server
  - LOG_LEVEL=DEBUG

Health Checks

Check server health:

make health

Or directly:

python -c "from src.mcp.server import get_server_health; import json; print(json.dumps(get_server_health(), indent=2))"

License

MIT License - feel free to use this as a starting point for your own MCP servers.

Contributing

This is a demo/seed project. Feel free to fork and extend it for your own needs.

Happy MCP Development! 🐄

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • DuckDuckGo MCP Server

    elliotnorrevik
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A basic MCP server with example tools including message echo functionality and server information retrieval. Built with FastMCP framework and supports both stdio and HTTP transports.
    -

  • DDG MCP2 Server

    elliotnorrevik
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A basic MCP server built with FastMCP framework that provides simple utility tools including message echoing and server information retrieval. Supports both stdio and HTTP transports with Docker deployment capabilities.
    -