# mcp-server-starter

Skeleton for building a Model Context Protocol (MCP) server in Python. Fork this when you need to expose a custom set of tools/data to Claude Desktop, Claude Code, or any MCP-compatible client.

## What's an MCP server?

[MCP](https://modelcontextprotocol.io/) is an open protocol that lets language-model clients call into external tools and data sources through a standard interface. An MCP server is the small process that hosts those tools — you write the functions, the protocol handles discovery and invocation.

## Quickstart

Install directly from this repository with [pipx](https://pipx.pypa.io/):

```bash
pipx install git+https://github.com/roderickch01/mcp-server-starter.git
```

Then register it with your MCP client. For Claude Desktop, edit `~/.config/Claude/claude_desktop_config.json` (Linux), `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "starter": {
      "command": "mcp-server-starter"
    }
  }
}
```

A copy of this snippet lives at [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json). Restart your client and the `echo` and `add` tools should appear.

## What's included

Two demo tools to verify the wiring:

- `echo(text: str) -> str` — returns `"echo: {text}"`
- `add(a: int, b: int) -> int` — returns the sum

Both live in [`src/mcp_server_starter/server.py`](src/mcp_server_starter/server.py) (under 30 lines).

## Adding your own tool

Open `server.py` and decorate any function with `@mcp.tool()`. The signature, type hints, and docstring become the tool's schema automatically:

```python
@mcp.tool()
def reverse(text: str) -> str:
    """Return the input string reversed."""
    return text[::-1]
```

Reinstall (`pipx reinstall mcp-server-starter`) and restart your MCP client. The new tool is discoverable.

## Local development

```bash
git clone https://github.com/roderickch01/mcp-server-starter.git
cd mcp-server-starter
python -m venv .venv && source .venv/bin/activate
pip install -e .
mcp-server-starter   # runs the server over stdio
```

## License

MIT — see [LICENSE](LICENSE).