# python-sdk: xây MCP server và client bằng Python — hướng dẫn cài đặt và dùng

> modelcontextprotocol/python-sdk là SDK Python chính thức cho Model Context Protocol, giúp bạn xây MCP server cung cấp tool, resource, prompt và xây client kết nối tới các server đó. Repo yêu cầu Python 3.11 trở lên; cài đặt khá gọn bằng uv hoặc pip.

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

Repo này là SDK Python chính thức cho Model Context Protocol (MCP), một chuẩn giúp ứng dụng LLM sử dụng dữ liệu và chức năng từ các server bên ngoài. Với gói Python `mcp`, bạn có thể viết server cung cấp công cụ, tài nguyên và prompt cho MCP host, hoặc viết client để kết nối tới MCP server khác.

Điểm đáng giá là SDK xử lý phần giao tiếp giao thức, kiểm tra dữ liệu và tạo schema từ type hint Python. Bạn chỉ cần viết các hàm Python có kiểu dữ liệu rõ ràng cùng docstring. Repo hiện có khoảng 24.844 sao và 4.122 fork, dùng giấy phép MIT.

Thư viện phù hợp với lập trình viên Python muốn đưa dữ liệu nội bộ, thao tác nghiệp vụ hoặc API riêng vào ứng dụng LLM theo một cách chuẩn hóa. Người mới cũng có thể bắt đầu bằng server có một tool cộng hai số, sau đó mở rộng dần.

```repo
- repo | modelcontextprotocol/python-sdk
- kind | Thư viện
- desc | SDK Python chính thức để xây MCP server, MCP client và kết nối LLM qua stdio, Streamable HTTP hoặc SSE.
- stars | 25k
- lang | Python
- license | MIT
```

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

- **Xây MCP server bằng Python:** Bạn có thể tạo server để LLM gọi các hàm nghiệp vụ, đọc dữ liệu hoặc nhận prompt. Ví dụ, một công ty có thể đưa hàm tra cứu đơn hàng vào server để ứng dụng LLM sử dụng khi trả lời khách.

- **Cung cấp tool cho MCP host:** Tool là các hàm mà mô hình hoặc ứng dụng LLM có thể gọi. SDK dùng type hint như `a: int` và `b: int` để suy ra schema, nên bạn không phải tự viết JSON Schema hay phần phân tích request.

- **Cung cấp resource:** Resource phù hợp với dữ liệu được định danh bằng URI. README minh họa resource mẫu `greeting://{name}`, trong đó tên được truyền vào URI để tạo lời chào tương ứng.

- **Viết MCP client:** Cùng một gói có thể kết nối tới MCP server. Client có thể gọi tool và đọc kết quả có cấu trúc, phù hợp khi bạn muốn xây một ứng dụng Python điều phối nhiều server MCP.

- **Hỗ trợ nhiều transport:** SDK hỗ trợ stdio, Streamable HTTP và SSE. Bạn có thể chạy server cục bộ qua subprocess hoặc phục vụ server qua HTTP khi triển khai.

- **Có công cụ dòng lệnh đi kèm:** Extra `cli` bổ sung lệnh `mcp`, gồm các lệnh `mcp dev`, `mcp run` và `mcp install`. Nhờ đó, bạn có thể chạy thử server, mở server qua transport cụ thể hoặc dùng các tác vụ CLI được SDK cung cấp.

- **Tự xử lý phần giao thức:** Bạn không phải tự viết phần parsing request, validation hay protocol handling cho ví dụ cơ bản. Đây là lợi ích lớn khi muốn tập trung vào logic nghiệp vụ thay vì chi tiết kết nối giữa LLM host và server.

- **Dùng được cho server và client trong cùng hệ sinh thái:** Nếu sản phẩm của bạn vừa cần công bố dữ liệu qua MCP vừa cần gọi các server khác, không cần ghép hai thư viện không liên quan. SDK này cung cấp cả hai phía.

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

- **Python 3.11 trở lên.** Đây là yêu cầu được ghi rõ trong README. Nếu máy đang dùng Python thấp hơn, bạn cần cài phiên bản phù hợp trước khi cài gói.

- **Một môi trường Python có thể cài gói.** README đưa ra hai lựa chọn là `uv` hoặc `pip`. README không ghi chi tiết cách cài Python, `uv` hay `pip`, nên bạn cần chuẩn bị sẵn một trong hai công cụ này.

- **Mã nguồn server hoặc client Python.** Để thử nhanh, bạn sẽ tạo file `server.py` theo ví dụ trong README. Khi viết client, bạn cần có một server đang chạy để client kết nối.

- **MCP Inspector nếu muốn kiểm tra server trực quan.** README hướng dẫn mở server trong MCP Inspector bằng `uv run mcp dev server.py`. Tài liệu không nêu yêu cầu phần cứng đặc biệt hay GPU.

- **Không có API key nào được nêu trong README cho ví dụ cơ bản.** Ví dụ chỉ cộng hai số và tạo lời chào. Nếu server riêng của bạn gọi dịch vụ khác, yêu cầu về key sẽ phụ thuộc vào dịch vụ đó, nhưng README của repo không mô tả phần này.

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

```steps
- Chuẩn bị Python | Kiểm tra máy có Python 3.11 trở lên
- Cài gói mcp | Cài SDK và tùy chọn CLI bằng uv hoặc pip
- Tạo server.py | Viết một server có tool và resource mẫu
- Chạy server thử | Mở server bằng MCP Inspector
- Chạy qua HTTP | Phục vụ server để client có thể kết nối
- Viết client | Gọi tool và in kết quả có cấu trúc
```

### Chuẩn bị Python

Cài hoặc chọn một môi trường Python có phiên bản từ 3.11. README chỉ nêu yêu cầu phiên bản, không cung cấp lệnh kiểm tra phiên bản cụ thể. Vì vậy, hãy kiểm tra bằng công cụ Python bạn đang dùng trước khi cài.

Tạo một thư mục làm việc riêng cho ví dụ, sau đó mở terminal tại thư mục đó. Bạn có thể lấy mã nguồn repo bằng lệnh phổ thông dưới đây nếu muốn xem đầy đủ ví dụ, tài liệu và test:

```bash
git clone https://github.com/modelcontextprotocol/python-sdk.git
cd python-sdk
```

Lệnh đầu tiên tải mã nguồn về máy. Lệnh thứ hai đi vào thư mục repo. Tuy nhiên, để dùng gói từ môi trường cài đặt, bạn không bắt buộc phải clone repo; README có hướng dẫn cài trực tiếp bằng `uv` hoặc `pip`.

### Cài gói mcp

README đưa ra lệnh cài có thêm extra `cli` như sau:

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

`uv add` thêm gói `mcp` cùng extra `cli` vào project. Phần `cli` cung cấp lệnh `mcp` với các tác vụ `mcp dev`, `mcp run` và `mcp install`.

Nếu bạn không cần công cụ dòng lệnh, README nói có thể cài gói `mcp` thuần. README không đưa ra lệnh riêng cho trường hợp này ngoài việc giải thích rằng có thể bỏ extra `cli`. Với một lệnh chạy thử không cần thêm gói vào project, README cũng nêu cách dùng:

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

Dấu `...` ở đây là phần đại diện cho lệnh `mcp` cụ thể. Khi dùng lệnh thật, bạn thay bằng `dev`, `run` hoặc tác vụ phù hợp. Người mới thường vấp ở chỗ đặt sai dấu ngoặc kép quanh `mcp[cli]`; hãy giữ đúng cách viết trong README.

### Tạo server.py

Tạo file `server.py` trong thư mục làm việc và chép đúng ví dụ 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}!"
```

Đoạn mã tạo một server tên `Demo`. Hàm `add` trở thành một tool nhận hai số nguyên và trả về tổng. Hàm `greeting` trở thành resource có URI mẫu `greeting://{name}`.

Bạn cần lưu đúng tên file là `server.py` nếu muốn dùng nguyên các lệnh trong README. Hai dấu gạch dưới trong docstring không phải phần bắt buộc để cộng số, nhưng docstring giúp mô tả chức năng cho hệ thống. Type hint `int` và `str` cũng quan trọng vì SDK dùng chúng để tạo schema và kiểm tra dữ liệu.

### Chạy server bằng MCP Inspector

Từ terminal đang mở tại thư mục chứa `server.py`, chạy:

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

Lệnh này khởi động server ở chế độ phát triển và mở nó trong MCP Inspector. Nếu terminal báo không tìm thấy `server.py`, nguyên nhân thường là bạn đang đứng sai thư mục hoặc đặt tên file khác. Hãy chuyển terminal về đúng thư mục chứa file trước khi chạy.

Trong Inspector, gọi tool `add` với `a=1` và `b=2`. Theo README, kết quả nhận được là `3`. Đây là cách kiểm tra nhanh cả phần khai báo tool, schema được suy ra từ type hint và việc gọi hàm.

### Chạy server qua Streamable HTTP

Để phục vụ `server.py` qua HTTP, chạy đúng lệnh:

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

README cho biết URL tương ứng để client kết nối là `http://localhost:8000/mcp`. Bạn cần giữ terminal này đang chạy trong lúc thử client. Nếu đóng terminal hoặc tiến trình dừng, client sẽ không thể gọi tool.

Lệnh `--transport streamable-http` chọn transport Streamable HTTP. SDK cũng hỗ trợ stdio và SSE, nhưng README chỉ đưa lệnh cụ thể cho Streamable HTTP trong ví dụ client này. Không nên tự đổi tên cờ nếu chưa kiểm tra tài liệu tương ứng.

### Viết client gọi tool

Tạo một file Python khác, hoặc chạy đoạn mã này trong môi trường có gói `mcp`:

```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())
```

Client mở kết nối tới URL HTTP của server, gọi tool có tên `add` và truyền hai tham số `a` và `b`. Kết quả được in từ `structured_content`, dự kiến là `{'result': 3}` theo README.

Hãy chạy server HTTP trước rồi mới chạy client. Nếu server không ở cổng hoặc đường dẫn mặc định, URL trong `Client` phải khớp với nơi server đang phục vụ. README cũng cho biết `Client` có thể khởi chạy server cục bộ như một subprocess stdio hoặc nhận transport tùy chỉnh, nhưng không đưa thêm đoạn lệnh chi tiết cho các trường hợp đó.

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

Có ba dấu hiệu rõ ràng để xác nhận ví dụ hoạt động:

- Sau khi chạy `uv run mcp dev server.py`, server mở được trong MCP Inspector.
- Khi gọi tool `add` với `a=1`, `b=2`, kết quả trả về là `3`.
- Sau khi chạy server bằng Streamable HTTP và chạy client, terminal của client in ra `{'result': 3}` từ `result.structured_content`.

Bạn nên kiểm tra theo đúng thứ tự. Nếu Inspector không mở, kiểm tra lại việc cài extra `cli`. Nếu client không kết nối, kiểm tra server HTTP còn chạy và URL có đúng là `http://localhost:8000/mcp` hay không.

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

### Chủ shop muốn đưa thao tác tính toán vào trợ lý

Một chủ shop có thể bắt đầu với những tool đơn giản như tính tổng tiền, tính số lượng hàng hoặc kiểm tra một quy tắc giá. Cách triển khai bám theo ví dụ là tạo một hàm Python có tham số kiểu rõ ràng, thêm decorator `@mcp.tool()` rồi chạy server trong MCP host hỗ trợ MCP.

Ví dụ, mẫu thao tác đầu tiên có thể là tool `add` nhận `a=1`, `b=2`. Khi gọi tool, kết quả trả về là `3`. Với nghiệp vụ thật, phần thân hàm sẽ thay phép cộng bằng logic đã có của cửa hàng. README không mô tả kết nối cơ sở dữ liệu, quản lý đơn hàng hay xác thực người dùng, nên các phần đó cần được thiết kế thêm.

### Nhân viên văn phòng muốn cung cấp dữ liệu có cấu trúc

Một nhóm có thể dùng resource để cung cấp nội dung theo URI. README minh họa `greeting://{name}`, trong đó server nhận `name` rồi trả về `Hello, {name}!`. Mô hình này có thể giúp bạn hình dung cách tạo resource theo mã định danh, nhưng README chưa cung cấp ví dụ dữ liệu văn phòng như bảng tính, tài liệu hoặc hệ thống chấm công.

Bạn có thể bắt đầu bằng resource mẫu, kiểm tra nó trong MCP Inspector, rồi đọc tài liệu của SDK để thay phần trả lời cố định bằng dữ liệu phù hợp. Cần tránh đưa dữ liệu nhạy cảm vào server thử nghiệm trước khi hiểu rõ quyền truy cập của MCP host.

### Lập trình viên mới muốn thử MCP trong vài phút

Lập trình viên Python mới có thể tạo `server.py` với tool và resource mẫu, cài `mcp[cli]`, rồi chạy:

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

Sau đó gọi `add` với `a=1`, `b=2` trong MCP Inspector. Kết quả `3` cho thấy bạn đã tạo được một MCP server cơ bản mà không cần tự viết JSON Schema, request parsing hoặc validation code.

Đây là cách học tốt vì mỗi phần có vai trò rõ: decorator công bố tool, type hint mô tả tham số, docstring giải thích chức năng, còn SDK xử lý giao thức.

### Dev muốn tách server và client qua HTTP

Khi muốn thử mô hình triển khai tách rời, chạy server bằng:

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

Sau đó dùng client kết nối tới `http://localhost:8000/mcp` và gọi:

```python
result = await client.call_tool("add", {"a": 1, "b": 2})
print(result.structured_content)
```

Kết quả mong đợi là `{'result': 3}`. Mô hình này phù hợp để hiểu cách một ứng dụng Python gọi tool qua Streamable HTTP, nhưng README chưa nói về triển khai production, reverse proxy, phân quyền hoặc giám sát.

> MCP giúp bạn biến các hàm và nguồn dữ liệu Python thành khả năng mà ứng dụng LLM có thể gọi theo chuẩn.
>
> — Ông T

```note
MCP server có thể mở dữ liệu và chức năng cho ứng dụng LLM. Hãy kiểm tra kỹ tool nào được công bố, dữ liệu nào được trả về và quyền truy cập trước khi dùng với dữ liệu nội bộ. README không mô tả chi phí dịch vụ, cơ chế xác thực hoặc chính sách lưu dữ liệu.
```

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

### Python thấp hơn phiên bản yêu cầu

README yêu cầu Python 3.11 trở lên. Nếu môi trường dùng Python cũ, việc cài hoặc chạy SDK có thể thất bại. Hãy chuyển sang Python đáp ứng yêu cầu rồi chạy lại lệnh cài; README không cung cấp lệnh nâng cấp cụ thể.

### Không tìm thấy lệnh mcp

Lệnh `mcp` được thêm bởi extra `cli`. Nếu bạn chỉ cài gói `mcp` thuần, các lệnh `mcp dev`, `mcp run` và `mcp install` có thể không có. Cài theo lệnh `uv add "mcp[cli]"` hoặc dùng `uv run --with "mcp[cli]" mcp ...` như README hướng dẫn.

### Không tìm thấy server.py

Lệnh `uv run mcp dev server.py` cần file `server.py` ở thư mục hiện tại. Hãy kiểm tra bạn đã lưu file đúng tên và mở terminal tại đúng thư mục. Không tự đổi sang tên khác nếu chưa sửa tên file trong lệnh.

### Client không kết nối được tới server

Server phải được chạy trước bằng `uv run mcp run server.py --transport streamable-http`. Client dùng URL `http://localhost:8000/mcp`, vì vậy hai tiến trình phải dùng đúng địa chỉ và đường dẫn. Nếu đã đóng terminal chạy server, hãy khởi động lại rồi chạy client.

### Tool trả về dữ liệu không như mong đợi

Trong ví dụ, tool `add` yêu cầu hai tham số `a` và `b` có kiểu `int`. Hãy gọi đúng tên tham số và truyền giá trị phù hợp, chẳng hạn `{"a": 1, "b": 2}`. Type hint và docstring nên được giữ chính xác để SDK tạo schema và mô tả tool đúng với logic.

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

Nên chọn repo này nếu bạn muốn xây MCP server hoặc client bằng Python, cần một SDK chính thức và muốn hỗ trợ các transport tiêu chuẩn gồm stdio, Streamable HTTP và SSE. Ví dụ khởi đầu ngắn, cách khai báo tool dễ đọc, và SDK giảm đáng kể phần code giao thức phải tự viết.

Repo cũng phù hợp để thử nghiệm nhanh với MCP Inspector. Lệnh cài đặt có sẵn extra CLI, còn cách tạo server cơ bản chỉ cần một file Python. Với người mới, việc type hint được dùng làm schema giúp giảm lượng cấu hình phải học.

Giới hạn là README chỉ mô tả ví dụ cơ bản. Nó chưa cung cấp trong phần tư liệu này hướng dẫn chi tiết về xác thực, phân quyền, cơ sở dữ liệu, triển khai production, chi phí, bảo vệ dữ liệu hay cách cài Python và uv trên từng hệ điều hành. README cũng không xác nhận riêng việc chạy trên Windows.

Nếu bạn cần một thư viện Python để làm MCP server/client và sẵn sàng đọc thêm tài liệu khi đi vào hệ thống thật, đây là lựa chọn đáng cân nhắc. Nếu chỉ cần một API web thông thường không có nhu cầu tích hợp với LLM host qua MCP, một framework web phù hợp với API truyền thống có thể đơn giản hơn.

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

### Repo này có miễn phí không?

Repo dùng giấy phép MIT. README không nêu chi phí dịch vụ hoặc chi phí vận hành, nên phần chi phí ngoài giấy phép chưa có thông tin trong tư liệu.

### Có cần GPU để chạy không?

README chỉ yêu cầu Python 3.11 trở lên và không nêu yêu cầu GPU. Ví dụ server cộng hai số cũng không đề cập phần cứng đặc biệt.

### Có chạy được trên Windows không?

Tư liệu được cung cấp không xác nhận riêng việc chạy trên Windows. README chỉ nêu yêu cầu Python 3.11 trở lên và các lệnh cài, chạy bằng uv hoặc pip.

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

Ví dụ cơ bản không cần API key; nó chỉ tạo tool cộng hai số và resource lời chào. Nếu server của bạn kết nối dịch vụ khác, README này không mô tả yêu cầu key cho trường hợp đó.

### SDK này dùng để xây server hay client?

Dùng được cho cả hai. SDK giúp xây MCP server cung cấp tool, resource và prompt, đồng thời cung cấp `Client` để kết nối tới MCP server và gọi tool.

### SDK hỗ trợ những cách kết nối nào?

README nêu ba transport tiêu chuẩn là stdio, Streamable HTTP và SSE. Ví dụ cụ thể trong README chạy server qua Streamable HTTP và client kết nối tới `http://localhost:8000/mcp`.
