macsymwang/hello-mcp-server

Hello World MCP Server

A simple "Hello World" MCP (Model Context Protocol) server built with FastMCP. This server demonstrates basic MCP functionality with several example tools.

Quick Start

Using uvx with GitHub (Recommended)

You can run this MCP server directly from GitHub using uvx:

uvx --from git+https://github.com/macsymwang/hello-mcp-server.git hello-mcp-server

MCP Client Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"]
    }
  }
}

Features

• say_hello: Greet someone with a personalized message
• get_server_info: Get information about the MCP server
• echo_message: Echo back any message you send
• count_words: Analyze text and count words/characters

Installation

Using uvx with GitHub (Recommended)

You can run this MCP server directly from GitHub using uvx:

uvx --from git+https://github.com/macsymwang/hello-mcp-server.git hello-mcp-server

Using uvx from PyPI (if published)

uvx hello-mcp-server

Local Installation

1. Clone or download this repository
2. Install the package:

pip install .

3. Run the server:

hello-mcp-server

Development Installation

For development, install in editable mode:

pip install -e .

Usage

Registering as Stdio Protocol

This MCP server is designed to work with the stdio transport protocol, which is the standard way MCP servers communicate with clients. The server reads JSON-RPC messages from stdin and writes responses to stdout.

MCP Client Configuration

Claude Desktop

Add this configuration to your Claude Desktop config file (usually located at ~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"]
    }
  }
}

Cursor IDE

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"],
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Generic MCP Client

For other MCP clients, use this configuration:

{
  "mcpServers": {
    "hello-world": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/macsymwang/hello-mcp-server.git", "hello-mcp-server"],
      "env": {},
      "transport": {
        "type": "stdio"
      }
    }
  }
}

Running the Server Manually

The server can also be started manually for testing:

1. Using uvx (recommended):

   uvx hello-mcp-server
   

2. Using the installed command:

   hello-mcp-server
   

3. Using Python module:

   python -m hello_mcp_server.server
   

4. Direct execution:

   python hello_mcp_server/server.py
   

When run manually, the server will wait for JSON-RPC messages on stdin. You can test it by sending MCP protocol messages, but it's typically used through MCP clients.

Available Tools

say_hello

Greets someone with a personalized message.

Parameters:

• name (optional): Name of the person to greet (default: "World")

Example:

{
  "name": "Alice"
}

get_server_info

Returns information about the MCP server.

Parameters: None

echo_message

Echoes back the provided message.

Parameters:

• message (required): The message to echo back

count_words

Analyzes text and provides word/character statistics.

Parameters:

• text (required): The text to analyze

Configuration

Stdio Protocol

This MCP server uses the stdio transport protocol, which means:

• Input: The server reads JSON-RPC messages from standard input (stdin)
• Output: The server writes JSON-RPC responses to standard output (stdout)
• Logging: Error messages and logs are written to standard error (stderr)

This is the standard protocol for MCP servers and ensures compatibility with all MCP clients.

Transport Configuration

The server automatically configures itself for stdio transport when started. No additional configuration is needed for the transport layer.

For advanced FastMCP configuration options, refer to the FastMCP documentation.

Requirements

• Python 3.8+
• fastmcp>=0.1.0

Project Structure

hello-mcp-server/
├── hello_mcp_server/
│   ├── __init__.py
│   └── server.py
├── pyproject.toml
└── README.md

Development

To contribute to this project:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is open source. Please check the license file for details.

Support

For issues and questions, please open an issue on the project repository.