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.
On this page5 sections
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:
uv add "mcp[cli]"
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:
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
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:
claude mcp add wordcount -- python C:\path\to\server.py
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:
claude mcp list
5. Call it
Ask for the tool by name so you can see it fire:
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,
install an existing MCP server, or generate the
claude mcp add command with the MCP config generator.