# simple-mcp

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server written
in Python, served over **Streamable HTTP** so it can be deployed remotely.

It exposes three demo tools:

| Tool           | Description                                            |
| -------------- | ------------------------------------------------------ |
| `add`          | Add two numbers.                                       |
| `echo`         | Echo back text — handy for testing connectivity.       |
| `current_time` | Current time in any IANA timezone (defaults to `UTC`). |

The MCP endpoint is served at **`/mcp`**.

## Run locally

With [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv run server.py
```

Or with plain pip:

```bash
pip install -r requirements.txt
python server.py
```

The server listens on `http://0.0.0.0:8000/mcp`. Override with the `HOST` and
`PORT` environment variables.

### Quick smoke test

```bash
curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

## Run with Docker

```bash
docker build -t simple-mcp .
docker run -p 8000:8000 simple-mcp
```

## Deploy (remote)

Any platform that runs a Docker container and injects a `$PORT` works
(the server reads `PORT` automatically).

**Render** (free tier, included `render.yaml`):

1. Push this repo to GitHub.
2. In Render: **New + → Blueprint**, select the repo. It reads `render.yaml`
   and provisions the service.
3. Your endpoint will be `https://<your-service>.onrender.com/mcp`.

**Railway / Fly.io / any VPS:** build the `Dockerfile` and expose the port the
platform provides. No code changes needed.

## Connect it to Claude

Once deployed, add the remote server by its URL. For **Claude Code**:

```bash
claude mcp add --transport http simple-mcp https://<your-service>.onrender.com/mcp
```

In **Claude Desktop** or **claude.ai**, add it under
*Settings → Connectors → Add custom connector* using the same `/mcp` URL.