# How to Build an MCP Server in Python

> Write a one-tool MCP server named word_count with the official Python SDK, run it over stdio, and call it from Claude Code with claude mcp add. Copy-paste.

- Canonical: https://guides-ai.pages.dev/guides/build-mcp-server-python/
- Plate 05.05 · Topic: MCP (https://guides-ai.pages.dev/topics/mcp/)
- Published: 06 Sept 2026 · 4 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

An MCP server is a small program that exposes tools to an AI client. With the official Python
SDK, a useful one is about ten lines.

## 1. Install the SDK

Python 3.10 or later:

```bash
uv add "mcp[cli]"
```

```bash
pip install "mcp[cli]"
```

The `cli` extra adds the `mcp` command (`mcp dev`, `mcp run`, `mcp install`). Note that
`pip install mcp` now installs the 2.x line, whose API differs from 1.x — pin `mcp>=1.28,<2`
if you have existing 1.x code.

## 2. Write the server

`server.py`:

```python
from mcp.server import MCPServer

mcp = MCPServer("wordcount")


@mcp.tool()
def word_count(text: str) -> int:
    """Count the words in a piece of text."""
    return len(text.split())


if __name__ == "__main__":
    mcp.run()
```

That's the whole server. The type hints *are* the schema — no JSON Schema, no request parsing,
no protocol code. The docstring becomes the tool description the model reads, so write it for
the model, not for yourself. `mcp.run()` defaults to the `stdio` transport, which is what a
local client launches.

## 3. Try it before wiring it up

```bash
uv run mcp dev server.py
```

That opens the server in the MCP Inspector, where you can call `word_count` by hand and see the
result. Fix schema mistakes here — it's much faster than debugging through a chat client.

## 4. Connect it to Claude Code

Point Claude Code at the interpreter and the absolute path to your file:

```powershell
claude mcp add wordcount -- python C:\path\to\server.py
```

```bash
claude mcp add wordcount -- python /path/to/server.py
```

If you installed the SDK into a virtualenv, use that environment's `python`, not the system
one. Then restart Claude Code and confirm it loaded:

```powershell
claude mcp list
```

## 5. Call it

Ask for the tool by name so you can see it fire:

```text
Use the word_count tool to count the words in the first paragraph of README.md.
```

Once it works, the interesting part is replacing `word_count` with something only your team has
— an internal API, a staging database query, a deploy status check.

---

Next: [build the same server in TypeScript](/guides/build-mcp-server-typescript/),
[install an existing MCP server](/guides/install-mcp-server-claude-code/), or generate the
`claude mcp add` command with the [MCP config generator](/tools/mcp-config/).