# modelcontextprotocol/python-sdk: viết MCP server và client bằng Python — hướng dẫn cài đặt và dùng

> modelcontextprotocol/python-sdk là bộ SDK Python chính thức của Model Context Protocol (MCP), dùng để viết server đưa công cụ và dữ liệu cho ứng dụng AI, hoặc client kết nối tới server MCP. Cài bằng một lệnh uv hoặc pip, cần Python 3.11 trở lên. Server đầu tiên chỉ khoảng 15 dòng code nên người mới cũng làm được.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-24 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/python-sdk-mcp-viet-server-client-bang-python

modelcontextprotocol/python-sdk là bộ SDK Python chính thức cho Model Context Protocol (MCP). Nó giúp bạn viết **MCP server** để đưa công cụ, dữ liệu và câu lệnh mẫu cho các ứng dụng AI, hoặc viết **MCP client** để kết nối tới bất kỳ server MCP nào. Gói Python tên là `mcp`.

MCP bạn có thể hiểu đơn giản như một kiểu web API, nhưng thiết kế riêng cho các mô hình ngôn ngữ lớn (LLM). Thay vì mỗi ứng dụng AI tự nghĩ ra cách nối với dữ liệu của bạn, MCP đặt ra một chuẩn chung. Bạn viết server một lần, các ứng dụng AI hỗ trợ MCP đều dùng được.

Repo này hợp với lập trình viên mới, người làm kỹ thuật trong doanh nghiệp, hay bất kỳ ai biết chút Python và muốn AI gọi được hàm của mình. Điểm đáng giá nhất: bạn không phải viết JSON Schema, không phải tự xử lý request hay kiểm tra dữ liệu. Hai hàm Python có chú thích kiểu và một docstring là đã có một server hoàn chỉnh. Repo hiện có khoảng 24.800 sao và 4.100 fork, giấy phép MIT.

```repo
- repo | modelcontextprotocol/python-sdk
- kind | Thư viện
- desc | SDK Python chính thức của Model Context Protocol: viết MCP server và MCP client chỉ với vài hàm Python có chú thích kiểu dữ liệu.
- stars | 25k
- lang | Python
- license | MIT
```

## python-sdk làm được gì

### Viết MCP server rất gọn

Bạn khai báo một đối tượng `MCPServer`, rồi gắn decorator lên hàm Python. Hàm nào thành **tool** (công cụ AI có thể gọi), hàm nào thành **resource** (dữ liệu AI có thể đọc). README cũng nhắc server còn có thể phơi ra **prompts**. Lợi ích thực tế: logic công ty bạn (tính giá, tra đơn, đọc dữ liệu nội bộ) đã nằm sẵn trong hàm Python thì chỉ cần thêm vài dòng là AI dùng được.

### Kiểu dữ liệu chính là schema

Khi bạn viết `a: int, b: int`, SDK dùng luôn phần chú thích đó làm schema. README nói rõ bạn không viết JSON Schema, không viết code phân tích request, không viết code kiểm tra dữ liệu, không lo phần giao thức. Người mới đỡ phải học nhiều thứ cùng lúc.

### Viết MCP client

Cùng một gói `mcp` còn là client đầy đủ. Lớp `Client` kết nối tới server qua địa chỉ URL, có thể khởi chạy một server cục bộ như tiến trình con (stdio), hoặc nhận một transport tự viết. Bạn dùng nó khi muốn chính chương trình của mình gọi tool trên một server MCP, thay vì đi qua ứng dụng AI.

### Hỗ trợ đủ các kiểu kết nối chuẩn

SDK nói được cả ba transport chuẩn: stdio, Streamable HTTP và SSE. README giải thích: địa chỉ URL nghĩa là Streamable HTTP, loại bạn dùng khi triển khai thật. Còn stdio hợp với server chạy ngay trên máy bạn.

### Công cụ dòng lệnh `mcp`

Kèm thêm phần `cli`, bạn có lệnh `mcp` với các lệnh con `mcp dev`, `mcp run`, `mcp install`. Trong README, hai lệnh `mcp dev` (mở server trong MCP Inspector để thử) và `mcp run` (chạy server) có ví dụ cụ thể. Lệnh `mcp install` chỉ được nhắc tên, README chưa giải thích; muốn dùng, bạn xem tài liệu chính thức của dự án.

## Cần chuẩn bị gì

Theo tư liệu, bạn cần:

- **Python 3.11 trở lên.** Đây là yêu cầu ghi trong README và `pyproject.toml`.
- **Trình quản lý gói `uv` hoặc `pip`.** README đưa cả hai cách cài. Nếu chưa có `uv`, bạn dùng `pip` đi kèm Python là được.
- **Một terminal.** Windows có thể dùng PowerShell, macOS/Linux dùng Terminal. README không giới hạn hệ điều hành.

Tư liệu không nói cần API key, tài khoản hay GPU nào để dùng SDK. Nếu server của bạn gọi dịch vụ bên ngoài thì key của dịch vụ đó là việc riêng của bạn.

Muốn thử server bằng giao diện trực quan, README dùng **MCP Inspector** (một công cụ riêng của dự án MCP). Lệnh `mcp dev` mở nó giúp bạn; README không nêu yêu cầu nào thêm, nên nếu máy báo thiếu gì thì bạn xem phần Inspector trong tài liệu chính thức.

## Cài đặt từng bước

```steps
- Kiểm tra Python | Chắc chắn máy có Python 3.11 trở lên
- Cài gói mcp | Cài `mcp[cli]` bằng uv hoặc pip
- Tạo server.py | Chép đoạn server mẫu 15 dòng vào một file
- Chạy thử với Inspector | Dùng `mcp dev` để gọi thử tool `add`
- Thử client | Chạy server bằng HTTP rồi gọi từ một client Python
```

### Kiểm tra phiên bản Python

Mở terminal và gõ lệnh dưới đây. Nếu số phiên bản thấp hơn 3.11, bạn cần cài Python mới trước khi làm tiếp.

```bash
python --version
```

### Cài gói mcp

README đưa hai cách tương đương. Dùng `uv` nếu bạn có sẵn dự án quản lý bằng uv, dùng `pip` nếu bạn quen cách cổ điển:

```bash
uv add "mcp[cli]"      # or: pip install "mcp[cli]"
```

Chú ý hai chỗ người mới hay vấp. Một, giữ nguyên dấu ngoặc kép quanh `mcp[cli]` để terminal không hiểu nhầm dấu `[ ]`. Hai, phần `cli` là thứ cung cấp lệnh `mcp`. Nếu bạn cài `mcp` trơn thì sẽ không có lệnh này.

Có thể bạn chỉ muốn thử nhanh mà không tạo dự án. README nói cách sau chạy được mà không cần dự án:

```bash
uv run --with "mcp[cli]" mcp ...
```

Thay dấu `...` bằng lệnh con bạn cần, ví dụ `dev server.py`.

### Tạo file server.py

Tạo một file tên `server.py` trong thư mục làm việc của bạn, rồi dán đoạn sau:

```python
from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"
```

Đây đã là một server MCP hoàn chỉnh, có một tool (`add`) và một resource có tham số (`greeting://{name}`). Docstring không chỉ là ghi chú: nó là phần mô tả để AI hiểu hàm dùng làm gì, nên bạn hãy viết rõ ràng.

### Mở bằng MCP Inspector

Đứng trong thư mục chứa `server.py` và chạy:

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

Lệnh này mở server trong MCP Inspector. Ở đó bạn chọn tool `add`, nhập `a=1`, `b=2` và nhận lại `3`.

### Chạy server qua HTTP và gọi bằng client

Để thử phần client, trước hết chạy server theo kiểu Streamable HTTP. Giữ cửa sổ terminal này mở:

```bash
uv run mcp run server.py --transport streamable-http
```

Mở một terminal thứ hai, tạo file client (ví dụ `client.py`) với nội dung sau:

```python
import asyncio

from mcp import Client

async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}

asyncio.run(main())
```

Rồi chạy file này bằng Python của môi trường đã cài `mcp`. Nếu bạn cài bằng `uv`, có thể dùng `uv run python client.py`.

```note
README ghi rõ địa chỉ mẫu là http://localhost:8000/mcp. Đây là địa chỉ chạy trên máy bạn. Khi đưa server ra ngoài mạng, hãy đọc kỹ tài liệu chính thức về triển khai và xác thực trước, vì server MCP có thể cho AI chạm vào dữ liệu thật của bạn.
```

## Kiểm tra đã chạy được chưa

Có hai dấu hiệu theo đúng README:

- **Với Inspector:** sau `uv run mcp dev server.py`, bạn gọi tool `add` với `a=1`, `b=2` và nhận kết quả `3`.
- **Với client:** khi server HTTP đang chạy, chạy file client sẽ in ra `{'result': 3}`.

Chỉ cần một trong hai cho thấy đúng kết quả là SDK đã cài xong và server của bạn đã hoạt động. Nếu muốn chắc hơn, bạn thử đổi `a`, `b` thành số khác và xem kết quả có đúng tổng không.

## Dùng vào việc thật

Các tình huống dưới đây bám sát những gì README cho thấy: server có tool và resource, client gọi được tool. Phần code mình viết thêm đều theo đúng mẫu trong README.

### Chủ shop cho AI tính tiền đơn hàng

Bạn bán hàng online, có sẵn quy tắc tính tiền (giá nhân số lượng, cộng phí ship). Bạn biết chút Python hoặc nhờ một bạn dev làm. Thay vì nhắn đi nhắn lại để AI tính tay, bạn viết một tool theo đúng mẫu `add`:

```python
@mcp.tool()
def order_total(price: int, quantity: int) -> int:
    """Tinh tong tien don hang theo don gia va so luong."""
    return price * quantity
```

Khi một ứng dụng AI hỗ trợ MCP kết nối server này, nó có thể gọi tool thay vì tự nhẩm. Kết quả là con số tính từ code của bạn, không phải từ trí nhớ của mô hình.

> Hai hàm Python có chú thích kiểu và một docstring là đã có một server MCP hoàn chỉnh.
>
> — Ông T

### Nhân viên văn phòng chia sẻ dữ liệu có tham số

Bạn ở bộ phận hành chính, cần một chỗ trả về lời chào hay đoạn văn mẫu theo tên từng khách. Resource trong README đúng loại này: địa chỉ `greeting://{name}` nhận tên và trả về câu chào. Bạn đổi nội dung trả về thành mẫu thư của công ty mình. Phần `{name}` trong địa chỉ chính là tham số được truyền vào hàm, nên một hàm phục vụ được cả nghìn khách.

### Lập trình viên thử server trước khi giao cho đồng nghiệp

Bạn viết xong server và muốn chắc nó chạy đúng trước khi cho ai dùng. Chạy `uv run mcp dev server.py`, mở Inspector, gọi từng tool với số liệu thật, xem kết quả. Cách này không cần ứng dụng AI nào, và bạn thấy ngay lỗi nằm ở code của mình hay ở chỗ khác.

### Lập trình viên viết chương trình tự động gọi server MCP

Bạn có một đoạn script chạy hằng ngày và muốn nó dùng tool của một server MCP có sẵn. Dùng `Client` với địa chỉ server, gọi `client.call_tool("tên_tool", {...})` như mẫu trong README, rồi lấy kết quả ở `result.structured_content`. Không cần ứng dụng AI ở giữa; script của bạn nói chuyện thẳng với server.

## Lỗi hay gặp và cách xử lý

### Báo không tìm thấy lệnh `mcp`

Nguyên nhân thường gặp: bạn cài `mcp` trơn thay vì `mcp[cli]`. README nói phần `cli` mới thêm lệnh `mcp`. Cài lại bằng `pip install "mcp[cli]"` hoặc `uv add "mcp[cli]"`, nhớ giữ dấu ngoặc kép. Nếu chỉ chạy thử một lần, dùng `uv run --with "mcp[cli]" mcp ...`.

### Cài lỗi hoặc báo sai phiên bản Python

Gói yêu cầu Python 3.11 trở lên. Chạy `python --version` để xem. Máy có nhiều bản Python thì lệnh `python` có thể trỏ nhầm bản cũ; kiểm tra lại bản bạn đang dùng trước khi cài.

### Client báo không kết nối được

Client trong ví dụ trỏ tới http://localhost:8000/mcp. Hãy chắc server đang chạy bằng `uv run mcp run server.py --transport streamable-http` ở một terminal khác và chưa bị tắt. Nếu server của bạn dùng cổng hoặc đường dẫn khác thì sửa URL cho khớp.

### Chép code từ bài hướng dẫn cũ rồi không chạy

README nhắc đến trang "What's new in v2" và một hướng dẫn chuyển đổi (migration). Nghĩa là cách viết giữa các phiên bản có thể khác nhau. Khi code từ bài cũ báo lỗi import hay tên lớp, hãy so với ví dụ trong README và đọc trang migration trên tài liệu chính thức của dự án.

### Tool chạy nhưng AI dùng sai hoặc không biết khi nào dùng

Đây thường không phải lỗi cài đặt mà là mô tả chưa rõ. Docstring và chú thích kiểu là thứ AI đọc để hiểu tool. Hãy viết docstring nói rõ hàm làm gì, tham số nghĩa là gì, và đặt tên hàm dễ hiểu.

## Có nên dùng không

**Điểm mạnh:** đây là SDK chính thức, giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. Viết server rất ngắn, không phải tự lo JSON Schema hay giao thức. Cùng một gói làm được cả server lẫn client, và hỗ trợ đủ stdio, Streamable HTTP, SSE. Cài đặt chỉ một lệnh.

**Giới hạn:** đây là thư viện cho người viết code, không phải ứng dụng bấm là chạy. Bạn cần biết Python ở mức cơ bản và dùng được terminal. README chỉ đưa ví dụ ngắn; phần xác thực, triển khai thật, các tính năng nâng cao phải đọc tài liệu chính thức. Tư liệu cũng không nói gì về hiệu năng hay giới hạn tải, nên mình không đánh giá được phần đó.

**Khi nào chọn cách khác:** nếu bạn không viết code và chỉ muốn dùng một công cụ MCP có sẵn thì bạn tìm server làm sẵn thay vì tự viết. Nếu dự án của bạn không dùng Python thì nên tìm SDK cho ngôn ngữ khác của dự án MCP. Còn nếu bạn muốn AI gọi hàm Python của mình mà không muốn tự xử lý giao thức, repo này là điểm khởi đầu hợp lý.

## Câu hỏi thường gặp

### python-sdk có miễn phí không?

Có. Repo dùng giấy phép MIT, bạn được dùng và sửa theo điều khoản của giấy phép đó. Tư liệu không nhắc đến phí nào cho chính SDK. Chi phí của các dịch vụ bên ngoài mà server của bạn gọi (nếu có) là việc riêng.

### Cần cài Python phiên bản nào?

Python 3.11 trở lên, theo cả README lẫn pyproject.toml. Bạn kiểm tra bằng lệnh python --version trước khi cài.

### Có cần GPU hay API key không?

Tư liệu không yêu cầu GPU hay API key để cài và chạy server mẫu. Server mẫu chỉ có hàm cộng hai số và một resource chào tên. Nếu server của bạn sau này gọi dịch vụ khác thì key của dịch vụ đó là chuyện riêng.

### Chạy được trên Windows không?

README không giới hạn hệ điều hành và không nêu riêng Windows. Cách cài bằng uv hoặc pip là lệnh phổ thông. Tư liệu chưa có thông tin kiểm chứng riêng cho Windows, nên nếu gặp vấn đề bạn xem tài liệu chính thức hoặc mục issues của repo.

### Khác nhau giữa `mcp` và `mcp[cli]` là gì?

`mcp[cli]` thêm công cụ dòng lệnh `mcp` với các lệnh con `mcp dev`, `mcp run`, `mcp install`. Cài `mcp` trơn thì bạn vẫn có SDK nhưng không có lệnh này. README khuyên cài `mcp[cli]` nếu bạn cần thử và chạy server nhanh.

### Dữ liệu của tôi có an toàn không?

README mô tả MCP là cách đưa dữ liệu và chức năng cho ứng dụng AI một cách an toàn và chuẩn hoá. Tư liệu không đi sâu vào bảo mật cụ thể cho từng cách triển khai. Repo có file SECURITY.md, bạn nên đọc khi định đưa server ra ngoài mạng.

### Tôi tìm tài liệu chi tiết ở đâu?

Tài liệu chính nằm ở trang chủ dự án: py.sdk.modelcontextprotocol.io. README cho biết có hướng dẫn bắt đầu, phần "What's new in v2", tài liệu tham khảo API và hướng dẫn chuyển đổi phiên bản. Repo cũng có thư mục docs, examples và file CONTRIBUTING.md nếu bạn muốn đóng góp.
