# Hello MCP Server

A simple Model Context Protocol (MCP) server that provides a greeting tool.

## Features

- Simple MCP server using FastMCP
- Dockerized with Podman support
- Uses `uv` as the Python package manager

## Prerequisites

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) - Python package manager
- [Podman](https://podman.io/) (optional, for containerized deployment)

## Local Development

### Install Dependencies

```bash
uv sync
```

### Run the Server

```bash
uv run mcp_server.py
```

The server will start and wait for MCP protocol messages via stdio.

## Docker/Podman Deployment

### Build the Image

```bash
podman build -t hello-mcp .
```

### Run the Container

**Interactive mode** (recommended for MCP servers):
```bash
podman run -it --name hello-mcp hello-mcp
```

**Using Docker Compose:**
```bash
podman-compose up
```

> **Note:** MCP servers communicate via stdio, so they must run in interactive mode (`-it`). Running in detached mode (`-d`) will cause the container to exit immediately.

## Connecting to Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration.

### Step 1: Locate Claude Desktop Config File

The configuration file location depends on your operating system:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Step 2: Add Server Configuration

Open (or create) the `claude_desktop_config.json` file and add the following configuration:

**Option A: Local Development (using uv)**
```json
{
  "mcpServers": {
    "hello-mcp": {
      "command": "uv",
      "args": ["run", "mcp_server.py"],
      "cwd": "/absolute/path/to/hello-mcp"
    }
  }
}
```

Replace `/absolute/path/to/hello-mcp` with the absolute path to this project directory.

**Option B: Using Podman Container**
```json
{
  "mcpServers": {
    "hello-mcp": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "hello-mcp"
      ]
    }
  }
}
```

> **Note:** Make sure the container image is built before using this configuration.

### Step 3: Restart Claude Desktop

After updating the configuration file, restart Claude Desktop to apply the changes.

### Step 4: Verify Connection

Once connected, you can ask Claude to use the `hello` tool. For example:
- "Use the hello tool from the hello-mcp server"
- "Call the hello function"

## Example Configuration File

See `claude-desktop-config.json.example` for a complete example configuration.

## Project Structure

```
hello-mcp/
├── mcp_server.py          # Main MCP server implementation
├── pyproject.toml         # Project dependencies and metadata
├── Dockerfile             # Container image definition
├── docker-compose.yml     # Docker Compose configuration
├── .dockerignore          # Files to exclude from Docker build
└── README.md             # This file
```

## Tools

### `hello`

Returns a greeting message.

**Example:**
```python
@server.tool()
def hello():
    """Returns a greeting"""
    return "Hello from MCP 👋"
```

## License

MIT