# modelcontextprotocol/python-sdk: xây MCP server và client — 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 server cung cấp tool, resource, prompt và client kết nối tới các server MCP. Cài đặt khá đơn giản nếu có Python 3.11 trở lên; gói có thêm CLI để chạy, phát triển và cài server.

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

modelcontextprotocol/python-sdk là SDK Python chính thức để xây dựng MCP server và MCP client. MCP là một giao thức tiêu chuẩn cho phép ứng dụng LLM truy cập dữ liệu và chức năng qua các server được thiết kế riêng, tương tự cách web API cung cấp dữ liệu cho ứng dụng.

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 các hàm tự động hóa vào ứng dụng LLM. Nhân viên văn phòng và chủ shop có thể hưởng lợi gián tiếp khi dev đóng gói các việc như tra cứu dữ liệu, tính toán hoặc gọi quy trình nội bộ thành tool cho AI sử dụng.

Điểm đáng giá nhất là bạn không phải tự viết phần xử lý giao thức, phân tích request hay JSON Schema cho các tham số có type hint. Một vài hàm Python có chú thích kiểu và docstring đã đủ để tạo MCP server có tool và resource.

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

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

- **Xây MCP server bằng Python:** Bạn có thể tạo server cung cấp tools, resources và prompts cho bất kỳ MCP host nào tương thích. Ví dụ, một hàm Python cộng hai số có thể trở thành tool để ứng dụng LLM gọi khi cần.

- **Xây MCP client:** Cùng một gói có thể kết nối tới MCP server. Điều này hữu ích khi bạn muốn viết ứng dụng Python tự động gọi tool, lấy resource hoặc kết hợp nhiều server trong một quy trình.

- **Hỗ trợ nhiều transport:** SDK nói được qua stdio, Streamable HTTP và SSE. Bạn có thể chạy server cục bộ dưới dạng tiến trình con, hoặc phục vụ qua HTTP khi cần triển khai.

- **Tự tạo schema từ type hint:** Với tham số như `a: int` và `b: int`, SDK có thể dùng thông tin kiểu để xử lý schema. Bạn không cần tự viết JSON Schema cho ví dụ cơ bản.

- **Có CLI đi kèm:** Phần cài đặt `mcp[cli]` thêm lệnh `mcp`, gồm các lệnh được README nêu như `mcp dev`, `mcp run` và `mcp install`. Nhờ vậy bạn có thể phát triển, chạy và cài server từ terminal.

- **Kiểm thử server bằng MCP Inspector:** Lệnh `mcp dev` mở server trong MCP Inspector. Đây là cách trực quan để gọi thử tool và xem kết quả trước khi tích hợp với ứng dụng lớn hơn.

- **Kết nối server HTTP bằng URL:** Client có thể nhận URL Streamable HTTP, chẳng hạn địa chỉ kết thúc bằng `/mcp`. Cách này phù hợp khi server được chạy như một dịch vụ riêng thay vì chỉ chạy cùng máy với client.

- **Kết nối server cục bộ qua stdio:** README cho biết `Client` cũng có thể khởi chạy server cục bộ như một subprocess stdio. Đây là lựa chọn tiện cho công cụ cá nhân hoặc server chỉ phục vụ một ứng dụng.

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

Bạn cần Python 3.11 trở lên. Đây là yêu cầu được ghi trong README và cũng là phiên bản tối thiểu mà dự án khai báo.

Bạn cần một môi trường có thể cài gói Python bằng `uv` hoặc `pip`. README đưa ra cả hai cách. Nếu muốn dùng các lệnh `mcp dev`, `mcp run` và `mcp install`, bạn cần cài extra `cli` bằng `mcp[cli]`. Nếu chỉ dùng SDK trong mã Python và không cần CLI, README nói có thể cài gói `mcp` thường.

Bạn cần tạo được một file Python, ví dụ `server.py`, để viết server. Khi chạy ví dụ HTTP, máy cần có thể dùng cổng cục bộ mà server mở. README không yêu cầu API key, tài khoản dịch vụ, GPU hay phần cứng đặc biệt cho các ví dụ này.

README không nêu hệ điều hành cụ thể. Vì vậy, tài liệu được cung cấp chưa đủ để khẳng định mọi khác biệt khi chạy trên Windows, macOS hoặc Linux. README cũng không nói chi phí sử dụng; chi phí của dịch vụ LLM hoặc hạ tầng bên ngoài, nếu bạn tích hợp thêm, không được mô tả trong tư liệu này.

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

```steps
- Chuẩn bị Python | Cài Python 3.11 trở lên và mở terminal
- Cài gói MCP | Cài SDK cùng CLI bằng uv hoặc pip
- Tạo server | Viết tool và resource trong server.py
- Chạy kiểm thử | Mở server bằng MCP Inspector
- Chạy qua HTTP | Khởi động server Streamable HTTP để client kết nối
- Viết client | Gọi tool và đọc kết quả từ URL MCP
```

### Chuẩn bị thư mục làm việc

Tạo một thư mục riêng cho ví dụ, sau đó mở terminal tại thư mục đó. Nếu bạn muốn lấy mã nguồn dự án để đọc thêm ví dụ, có thể dùng lệnh clone phổ thông sau:

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

Lệnh đầu tiên tải mã nguồn SDK về thư mục `python-sdk`. Lệnh thứ hai chuyển terminal vào thư mục đó. Bạn không bắt buộc phải clone repo nếu chỉ muốn cài gói từ trình quản lý Python; README hướng dẫn cài trực tiếp bằng `uv` hoặc `pip`.

Nếu terminal báo không nhận ra `git`, hãy cài Git hoặc dùng thư mục dự án Python hiện có. README không ghi thêm quy trình cài Git, nên phần này chỉ là bước chuẩn bị thông thường.

### Cài SDK và CLI

README đưa ra hai cách cài đặt:

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

Với `uv`, lệnh thêm gói MCP và phần CLI vào dự án. Phần `cli` là extra, giúp có lệnh `mcp dev`, `mcp run` và `mcp install`.

Nếu bạn dùng pip, chạy phần lệnh được ghi trong chú thích:

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

Hãy chạy lệnh trong đúng môi trường Python mà bạn sẽ dùng để chạy `server.py`. Lỗi thường gặp của người mới là cài vào một Python nhưng chạy bằng Python khác, khiến terminal báo thiếu gói hoặc thiếu lệnh `mcp`.

Nếu chỉ cần thư viện và không cần CLI, README cho biết có thể cài plain `mcp`:

```bash
pip install mcp
```

README cũng nêu cách chạy lệnh một lần mà không cần thêm gói vào dự án:

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

Dấu `...` trong ví dụ là phần lệnh MCP bạn muốn chạy tiếp, không phải chuỗi cần gõ nguyên văn trong mọi tình huống.

### Tạo server đầu tiên

Tạo file tên `server.py` trong thư mục làm việc và chép nội dung 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}!"
```

Dòng `from mcp.server import MCPServer` lấy lớp server từ gói `mcp`. `MCPServer("Demo")` tạo server tên Demo.

Phần `@mcp.tool()` biến hàm `add` thành một tool mà MCP host có thể gọi. Hai tham số `a` và `b` có kiểu `int`, còn kết quả cũng là `int`. Docstring mô tả ngắn mục đích của tool.

Phần `@mcp.resource("greeting://{name}")` tạo một resource dạng mẫu. Khi có tên, hàm trả về lời chào tương ứng. Bạn cần lưu ý tên file phải đúng là `server.py` nếu muốn dùng nguyên các lệnh trong README.

README nhấn mạnh rằng ví dụ này không cần bạn tự viết JSON Schema, code phân tích request, code validation hoặc phần xử lý giao thức. Type hint và docstring đảm nhận phần mô tả cơ bản cho SDK.

### Mở server trong MCP Inspector

Từ terminal đang đứng trong thư mục có `server.py`, chạy:

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

Lệnh này chạy server ở chế độ phát triển và mở nó trong MCP Inspector. Nếu bạn mở terminal ở thư mục khác, hãy dùng đường dẫn đúng tới `server.py` hoặc chuyển về thư mục chứa file trước khi chạy.

Trong Inspector, gọi tool `add` với `a=1` và `b=2`. Kết quả mong đợi là `3`. Đây là kiểm tra trực tiếp cho thấy server đã đăng ký tool và SDK đã xử lý tham số theo type hint.

README không đưa ra thêm lệnh kiểm thử riêng cho resource trong phần ví dụ ngắn. Bạn có thể xem tài liệu bắt đầu và các ví dụ trong repo để biết cách khám phá resource sâu hơn.

### Chạy server qua Streamable HTTP

Để phục vụ `server.py` qua HTTP, chạy:

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

Lệnh `mcp run` chạy file server. Cờ `--transport streamable-http` chọn transport Streamable HTTP. Theo ví dụ trong README, server sẽ được client truy cập tại `http://localhost:8000/mcp`.

Giữ terminal này đang chạy trong lúc thử client. Nếu đóng terminal, server HTTP dừng và client sẽ không thể kết nối tới địa chỉ đó.

### Viết client gọi tool

Tạo một file Python khác hoặc đặt đ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` nhận URL MCP và mở kết nối trong khối `async with`. `call_tool` gọi tool tên `add` với hai giá trị đầu vào. `result.structured_content` in ra nội dung có cấu trúc; theo README, kết quả mong đợi là `{'result': 3}`.

URL trong ví dụ dùng Streamable HTTP, là transport được README mô tả cho triển khai. README cũng cho biết `Client` có thể khởi chạy server cục bộ qua stdio hoặc nhận custom transport, nhưng không đưa mã đầy đủ cho hai trường hợp đó trong phần hướng dẫn ngắn.

```note
Không đưa API key, mật khẩu hoặc dữ liệu nhạy cảm vào tool, resource hay log khi chưa kiểm tra quyền truy cập. MCP server có thể expose chức năng và dữ liệu cho MCP host, nên hãy giới hạn những gì server được phép cung cấp.
```

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

Có ba dấu hiệu chính để kiểm tra theo đúng ví dụ README.

Thứ nhất, lệnh cài đặt hoàn tất mà không báo lỗi thiếu phiên bản Python hoặc không tìm thấy gói. Nếu dùng `mcp[cli]`, terminal cần nhận được các lệnh CLI được README nêu.

Thứ hai, khi chạy:

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

server xuất hiện trong MCP Inspector. Gọi tool `add` với `a=1`, `b=2` và nhận `3`. Đây là kết quả kiểm tra rõ nhất cho server đầu tiên.

Thứ ba, khi chạy server HTTP bằng:

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

client có thể kết nối tới `http://localhost:8000/mcp`. Đoạn client trong README phải in:

```python
{'result': 3}
```

Nếu client không kết nối được, trước hết kiểm tra server HTTP còn đang chạy, địa chỉ và đường dẫn `/mcp` có đúng như ví dụ hay không.

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

### Chủ shop tạo tool tính nhanh đơn hàng

Một dev có thể thay hàm `add` bằng hàm tính tổng tiền hoặc phí vận chuyển của shop. Các tham số Python có type hint giúp mô tả đầu vào rõ ràng để MCP host gọi tool. Ví dụ trong README chứng minh mô hình cơ bản: khai báo hàm, gắn `@mcp.tool()`, nhận tham số và trả kết quả.

Sau khi viết server, dev chạy:

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

Trong MCP Inspector, thử các giá trị đơn hàng và kiểm tra kết quả trước khi đưa server cho ứng dụng LLM. Kết quả nhận được là dữ liệu trả về từ hàm Python, thay vì phải tự viết lớp xử lý giao thức.

### Nhân viên văn phòng tra cứu một resource chuẩn hóa

Một phòng ban có thể đóng gói các nội dung ít thay đổi thành resource. Ví dụ `greeting://{name}` trong README cho thấy server có thể nhận một phần biến trong URI rồi trả về nội dung tương ứng.

Dev có thể mở rộng cùng kiểu này cho dữ liệu được phép chia sẻ, sau đó để MCP host đọc resource theo tên phù hợp. README chỉ minh họa resource lời chào, nên cần tự kiểm tra tài liệu dự án trước khi áp dụng cho dữ liệu nghiệp vụ phức tạp.

### Dev xây ứng dụng Python gọi server nội bộ

Khi có một server chạy qua HTTP, ứng dụng Python có thể dùng `Client` để gọi tool. Quy trình theo README là chạy:

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

Sau đó dùng client gọi:

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

Kết quả có thể được đưa vào bước tiếp theo của quy trình tự động hóa. Ví dụ của README trả về `{'result': 3}`, cho thấy client nhận được dữ liệu có cấu trúc thay vì chỉ một chuỗi hiển thị.

### Đội phát triển thử tool trước khi tích hợp LLM

Một đội dev có thể dùng MCP Inspector làm bước kiểm tra thủ công. Họ mở server bằng `mcp dev`, gọi từng tool với giá trị đầu vào đại diện cho tình huống thật và xác nhận kết quả.

Cách này giúp phát hiện lỗi ở hàm Python, tên tool, tham số hoặc quyền truy cập trước khi kết nối với MCP host. README mô tả chính xác luồng thử `add` với `a=1`, `b=2` và nhận `3`.

> MCP biến các hàm Python và dữ liệu được chọn thành giao diện mà ứng dụng LLM có thể sử dụng.
>
> — Ông T

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

### Python thấp hơn 3.11

SDK yêu cầu Python 3.11 trở lên. Nếu trình cài đặt báo không phù hợp, kiểm tra lại Python đang được terminal sử dụng và chuyển sang môi trường có phiên bản đáp ứng yêu cầu. Không nên tự hạ phiên bản gói khi README không hướng dẫn cách đó.

### Có SDK nhưng không có lệnh mcp

Nguyên nhân dễ gặp là bạn cài plain `mcp` nhưng lại muốn dùng `mcp dev` hoặc `mcp run`. README nói phần `cli` mới thêm công cụ dòng lệnh, nên hãy cài `mcp[cli]` nếu cần CLI.

### Chạy sai thư mục hoặc sai tên file

Lệnh README dùng `server.py`. Nếu file có tên khác hoặc terminal đang ở thư mục khác, lệnh có thể không tìm thấy server. Hãy kiểm tra file thực tế và mở terminal tại thư mục chứa file trước khi chạy.

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

Hãy giữ lệnh `uv run mcp run server.py --transport streamable-http` đang chạy. Sau đó kiểm tra client dùng đúng địa chỉ `http://localhost:8000/mcp` như README. Nếu bạn đổi transport, cổng hoặc đường dẫn, mã client cũng phải phù hợp; README không cung cấp cấu hình thay thế chi tiết.

### Tool trả về kết quả khác mong đợi

Kiểm tra tên tool và dữ liệu truyền vào. Ví dụ chuẩn dùng tên `add` cùng hai khóa `a` và `b`, đều là số nguyên. Khi kiểm tra, hãy bắt đầu bằng đúng cặp `a=1`, `b=2` để tách lỗi môi trường khỏi lỗi logic trong hàm.

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

Nên dùng nếu bạn đang làm Python và muốn xây MCP server hoặc client theo giao thức chuẩn. SDK có API ngắn, hỗ trợ cả server lẫn client, có CLI, có Inspector cho phát triển và hỗ trợ stdio, Streamable HTTP cùng SSE. Giấy phép của dự án là MIT, và repo hiện có khoảng 24.844 sao cùng 4.122 fork.

Thư viện đặc biệt hợp với đội muốn đưa các hàm nội bộ, resource hoặc quy trình tự động hóa tới nhiều MCP host. Cách dùng type hint để mô tả tham số cũng giúp ví dụ đầu tiên khá gọn.

Giới hạn là README được cung cấp chưa mô tả chi tiết việc xác thực, phân quyền, triển khai production, bảo vệ dữ liệu, chi phí hạ tầng hay cách tích hợp với từng MCP host. Bạn cũng cần tự thiết kế lớp an toàn nếu server chạm tới dữ liệu khách hàng hoặc thao tác có hậu quả thật.

Nếu bạn chỉ cần một script Python chạy độc lập, không cần LLM hoặc MCP host, SDK này có thể là phần phụ không cần thiết. Nếu cần triển khai nghiêm túc, hãy đọc thêm tài liệu bắt đầu, API reference, hướng dẫn client, migration guide và các ví dụ trong repo trước khi chốt kiến trúc.

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

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

Repo dùng giấy phép MIT. README không nêu chi phí sử dụng SDK. Chi phí của các dịch vụ hoặc hạ tầng bên ngoài, nếu có, chưa được đề cập.

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

README chỉ yêu cầu Python 3.11 trở lên và không nêu yêu cầu GPU. Các ví dụ server, client và Inspector không đề cập phần cứng đặc biệt.

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

README được cung cấp không nêu hệ điều hành cụ thể. Vì vậy chưa có đủ thông tin trong tư liệu để khẳng định chi tiết cách chạy trên Windows.

### Có cần API key hoặc tài khoản LLM không?

Các ví dụ trong README không yêu cầu API key hay tài khoản LLM. SDK xây MCP server và client; việc kết nối dịch vụ bên ngoài có thể cần cấu hình riêng nhưng chưa được mô tả.

### SDK này xây server hay client?

Xây được cả hai. Server có thể expose tools, resources và prompts; client có thể kết nối tới MCP server qua URL, stdio subprocess hoặc custom transport.

### Transport nào được hỗ trợ?

README nêu ba transport tiêu chuẩn: stdio, Streamable HTTP và SSE. Ví dụ triển khai HTTP dùng `--transport streamable-http` và URL `http://localhost:8000/mcp`.

### Khác gì so với tự viết web API Python?

MCP được thiết kế cho tương tác giữa ứng dụng LLM và server, còn web API thường phục vụ ứng dụng nói chung. SDK tự xử lý phần giao thức và có thể tạo schema cơ bản từ type hint, nhưng README không so sánh trực tiếp với framework web cụ thể.
